## Basic There are some components that you can use to represent command line options/flags. These are called components because they are not exact one-to-one correspondence to the controls that will be rendered. Here is a structure of the abstraction layers: ``` ┌────────────────────┐ │ GUI Representation │ └────────────────────┘ ⬆ Rendering & Data Binding ┌────────────┐ │ Components │ └────────────┘ ⬆ Parsing ┌──────────┐ │ XML File │ └──────────┘ ⬆ Conversion by User ┌─────────────────────┐ │ Command Line Syntax │ └─────────────────────┘ ``` Most components are binded to a value which can be viewed as a field for some command line arguments. But there are 2 exceptions: - `infix`: not visible because it is for automation and joining different commands in a single execution - `separator`: not part of the command line, but it is purely for visual so that it is easier to group components of similar functions ### Common Attributes #### `description` A brief description of the flags/values that this component represents. It can be any length, but better to be succinct. - Required. Otherwise the program will throw an exception upon parsing. #### `longName` The long name of the flag that this component represents. It should usually be in the form of `--[something]`. > Of course if you are on Windows, the syntax would be like `/`. > > The program technically doesn’t care about whether the name follows a valid syntax. Upon compilation, it will just merge these into a long string so this field could even be used as ~~an exploitation~~ clever way for unintended purposes - Optional. If left empty, the program will assume this specific argument has no long names #### `shortName` Same as long name. Just because *nix (and also Windows) has this shorthand. > Note: if both `shortName` and `longName` are left empty , then the compiled string will be like `... [value]` #### `required` Indicates if a component is required to complete the command. - Optional. Leave it empty for *“Not Required”* - Type: `boolean` #### `useEqualConnector` Indicates if use the equal sign `=` to connect argument names and values. For example, `--verbose=true` vs. `--verbose true` - Optional. The default is whitespace - Type: `boolean` --- ## Infix > **Note:** This is a special component that does not have the common attributes. This is a special component for automation. Because components will be compiled to a single command and then executed, so it is possible to utilize this feature by joining fields with special strings. For example, ```shell ls [arg1] | grep [arg2] ``` can be described as ```xml ``` ### Attributes #### `code` The command segment for automation - Required --- ## number This is the component for entering a number, whether it to be a decimal or an integer. ### Attributes #### `customDefault` The default value of this component. Note not to be confused with the default value of the underlying command. **This is supposed to be a custom value set by the user** to automatically fill in values. - Optional. Leave it empty if there is no need to specify any custom value. When the GUI is auto-generated, *Guify* will use this value to fill in the blanks. Users can always reset the modified values back to this custom default value. Note if there is no custom default value and the user doesn’t supply any value, the field will be skipped upon unparsing (in order to use the underlying command’s default value) - Type: `float` #### `max` The maximum value - Optional. By default it is `float.MaxValue` - Type: `float` #### `min` The minimum value - Optional. By default it is `float.MinValue` - Type: `float` --- ## openFile This is the component for popping up a open file dialog. It allows multiple files to be selected at once. ### Attributes #### `customDefaultFolder` The usual `customDefault` value is split into two fields here. `customDefaultFolder` is the default value for folder. #### `customDefaultFileName` `customDefaultFileName` is the default value for the file name. #### `multiple` - Optional. By default this component only allows for selecting one file at a time - Type: `boolean` --- ## pickValue This is basically a dropbox that supports a collection of distinct values. It is best suited for enum-like arguments, for example `–-mode 0` ### Attributes #### `customDefault` The default value of this component. Note not to be confused with the default value of the underlying command. **This is supposed to be a custom value set by the user** to automatically fill in values. - Optional. Leave it empty if there is no need to specify any custom value. When the GUI is auto-generated, *Guify* will use this value to fill in the blanks. Users can always reset the modified values back to this custom default value. Note if there is no custom default value and the user doesn’t supply any value, the field will be skipped upon unparsing (in order to use the underlying command’s default value), and the corresponding `ListBox` control will not have anything preselected. If it is set to anything that is not listed in candidates (except for empty string), it will throw an error. - Type: `string` ### Inner Nodes The inner nodes can only be type of `candidate` which is just a valid value that users can choose. It can have these attributes: - `value`: the value of this candidate - Required - `description`: the tooltip when mouse is hovering - Optional. The tooltip will not be generated if this attribute is empty or not specified at all --- ## saveFile It is pretty much the same as [`openFile`](#openFile). ### Attributes #### `customDefaultFolder` The usual `customDefault` value is split into two fields here. `customDefaultFolder` is the default value for folder. #### `customDefaultFileName` `customDefaultFileName` is the default value for the file name. --- ## selectFolder ### Attributes #### `customDefault` The default path. Note not to be confused with the default value of the underlying command. **This is supposed to be a custom value set by the user** to automatically fill in values. - Optional. Leave it empty if there is no need to specify any custom value. When the GUI is auto-generated, *Guify* will use this value to fill in the blanks. Users can always reset the modified values back to this custom default value. Note if there is no custom default value and the user doesn’t supply any value, the field will be skipped upon unparsing (in order to use the underlying command’s default value) --- ## String This component is an abstraction of any string typed fields in a command line program. Although it can also be inputs of other types such as booleans, integers and floats, and even argument lists, it is advised to use specialized components for them. ### Attributes #### `customDefault` The default value of this component. Note not to be confused with the default value of the underlying command. **This is supposed to be a custom value set by the user** to automatically fill in values. - Optional. Leave it empty if there is no need to specify any custom value. When the GUI is auto-generated, *Guify* will use this value to fill in the blanks. Users can always reset the modified values back to this custom default value. Note if there is no custom default value and the user doesn’t supply any value, the field will be skipped upon unparsing (in order to use the underlying command’s default value) --- ## Separator > **Note:** This is a special component that does not have the common attributes This is a visual separator between groups of controls. Use a separator if it makes more sense to put some controls/components together. ### Attributes #### `label` You can choose to have a label for the following group of controls - optional. Default to empty. --- ## YesNo This component is an abstraction of flags/Boolean values. ### Attributes #### `group` Indicates which group this component belongs to. This attribute determines whether the auto-generated GUI control should be a check box or a radio button - Optional. Leave it empty if this flag is independent of any other flags, i.e. it is best represented as a check box with no restrictions. If the group has a meaningful name (i.e. not empty nor skipped), *Guify* will try to find other `YesNo` components associated with the same group name and convert them to a radio button group #### `customDefault` The default value of this component. Note not to be confused with the default value of the underlying command. **This is supposed to be a custom value set by the user** to automatically fill in values. - Optional. Leave it empty if there is no need to specify any custom value. When the GUI is auto-generated, *Guify* will use this value to fill in the blanks. Users can always reset the modified values back to this custom default value. Note if there is no custom default value and the user doesn’t supply any value, the field will be skipped upon unparsing (in order to use the underlying command’s default value) - Type: `bool` #### `isFlag` Indicates whether this component should be interpreted as a flag, > - If set to `true`, then it is a flag and will be compiled as `... --flag` > - If `false`, then it is `... –-flag [true|false]` - Optional. Leave it empty for `true`