AFXKeywords

Keywords generate the arguments to a GUI command. These keywords belong to the command, but the keywords are also stored as members of the mode. As a result, you can easily connect the keywords to widgets in a dialog box that updates the value of the keywords. For more information, see Dialog boxes.

AFXKeyword is the base class for keywords in the toolkit. The AFXKeyword class derives from a data target, so it automatically keeps the GUI and application data synchronized with each other. For more information, see Data targets.

The AFXKeyword class extends the functionality of the FXDataTarget class by holding additional values, such as the name of the keyword, a default value, and a previous value. The keyword’s GUI command uses this information to construct a kernel command string.

You can designate a keyword as optional or required. A required keyword is always issued by the GUI command. An optional keyword, whose values have not changed since the last commit of the command, is not issued by the GUI command. If none of the keywords has changed since the last commit, no GUI command will be issued when the mode is committed.

The following types of keywords are supported: 

  •  AFXIntKeyword(cmd, name, isRequired, defaultValue)
  •  AFXFloatKeyword(cmd, name, isRequired, defaultValue)
  •  AFXStringKeyword(cmd, name, isRequired, defaultValue)
  •  AFXBoolKeyword(cmd, name, booleanType, isRequired,
     defaultValue)
  •  AFXSymConstKeyword(cmd, name, isRequired, defaultValue)
  •  AFXTupleKeyword(cmd, name, isRequired, minLength,
     maxLength, opts)
  •  AFXTableKeyword(cmd, name, isRequired, minLength,
     maxLength, opts)
  •  AFXObjectKeyword(cmd, name, isRequired, defaultValue)

The type of data supported by each keyword is implied from the name of its constructor, except for AFXObjectKeyword. An object keyword is one that supports specifying a variable name as the keyword's value.

The prototypes for all the keywords are similar. The first two arguments of a keyword are:

  • A GUI command object.

  • A String specifying the name of the keyword.

All keywords also support an argument that determines whether the keyword is required or optional. If a keyword is required, it will always be sent with the command. If a keyword is optional, it will be sent only if its value changes. However, if the keyword is connected to a widget that is hidden, then the keyword will not be sent regardless of whether it is required or optional.

Most keywords support the specification of a default value. When you construct a keyword, its value is set to the default value. If you use the keyword's setDefaultValue method to change the default value, you will not affect the value of the keyword unless you also call the keyword's setValueToDefault method. In contrast, if you want to change only the value of the keyword, without changing its default value, you should use the keywords' setValue method.

When the mode issues the command to the kernel, the keywords will be ordered in the same order in which they were created in the mode.

When storing keywords in the mode class, the convention is to name the keyword object using the same name as the keyword label plus Kw. For example, 

self.rKw = AFXIntKeyword(self.cmd, 'r',  True)
self.tKw = AFXFloatKeyword(self.cmd, 't',  True)
self.nameKw = AFXStringKeyword(cmd, 'name', True, 'Part-1')
self.twistKw = AFXBoolKeyword(cmd, 'twist',
    AFXBoolKeyword.ON_OFF, 0) 
self.typeKw = AFXSymConstKeyword(cmd, 'type', True,
    SHADED.getId())
self.imageSizeKw = AFXTupleKeyword(cmd, 'imageSize', False,
    1, 2, AFXTUPLE_TYPE_FLOAT)