Skip to content

Components

Jump to bottom
Quantumzhao edited this page Jul 1, 2022 · 6 revisions

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 /<something>.

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,

ls [arg1] | grep [arg2]

can be described as

<root command="ls">
	<selectFolder description="..." />
	<infix code="| grep" />
	<string description="..." />
</root>

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.

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

Clone this wiki locally