You use the AFXGuiCommand class to construct a GUI command. The AFXGuiCommand class takes the following arguments:

cmd = AFXGuiCommand(self, 'setValues', 
    'session.graphicsOptions', TRUE)

Most commands in ABAQUS/CAE operate on the current object; for example, the current viewport or the current part. As a convenience, modes recognize a special syntax when interpreting the object specified in a GUI command. If you place %s between square brackets following certain repositories, the mode replaces the %s with the current name. You should always use this %s syntax, as opposed to hard-coding a name, so that the current name will always be used in commands.

The following current objects are supported:

If a command edits an object, you should request that a query be registered on that object by specifying TRUE for the registerQuery argument in the GUI command constructor. Registering a query will cause the keywords associated with the AFXGuiCommand to be updated with the kernel values when the mode is started and any time the kernel values change. For example,

cmd = AFXGuiCommand(
    mode,'PointSection','mdb.models[%s]', TRUE)

In addition, modes recognize session.viewports[%s] as a special repository. The mode registers a query on the session automatically so that the command will be kept up-to-date if the user switches the current viewport. The following examples illustrate the special syntax:

cmd = AFXGuiCommand(
    mode,'setValues','session.viewports[%s]',TRUE)

cmd = AFXGuiCommand(
    mode,'bringToFront','session.viewports[%s]', TRUE)

The ABAQUS GUI Toolkit employs a target/message system to achieve communication within the GUI process. The target/message system is in contrast to, for example, Motif’s callback mechanism. All widgets can send and receive messages from any other widget. A message consists of two components:

Most widgets in the ABAQUS GUI Toolkit take arguments that specify their target and their ID. Even if a widget does not take a target and ID as arguments, you can set these attributes using the setTarget and setSelector methods. For example,

    FXButton(parent, 'Label', tgt=self, sel=self.ID_1)
	
    groupBox = FXGroupBox(parent)
    groupBox.setTarget(self)
    groupBox.setSelector(self.ID_2)

Widgets are capable of sending several types of messages. Two of the most common message types are SEL_COMMAND and SEL_UPDATE. The SEL_COMMAND message type generally indicates that a widget was “committed”; for example, the user clicked a push button. The SEL_UPDATE message is sent when a widget is requesting its target to update its state; for more information, see “Automatic GUI updating,” Section 6.5.5.

A message is routed to a message handler using a map defined in the target class. You add an entry in the map by specifying which method to call when a message of a certain type and ID is received. These concepts are illustrated in Figure 6–2.

The message map is defined by using the FXMAPFUNC function (see example below). This macro takes four arguments: self, message type, message ID, and method name. The method name must be qualified by the class name: className.methodName. When a message is received whose type and ID match those defined in an FXMAPFUNC entry, the corresponding method will be called. If you have a large range of IDs that you want to define in the message map, you can use the FXMAPFUNCS function, which takes one additional argument: self, message type, start message ID, end message ID, and method name.

Objects react to messages using message handlers. All message handlers have the same prototype, which contains the following:

The following code shows how message maps, message IDs, and message handlers work together:

class MyClass(BaseClass):         

    [         
        ID_1,
        ID_2,
        ID_LAST     
    ] = range(BaseClass.ID_LAST, BaseClass.ID_LAST+3)

    def __init__(self):              

        BaseClass.__init__(self)
        FXMAPFUNC(self, SEL_COMMAND, self.ID_1, 
            MyClass.onCmdPrintMsg)
        FXMAPFUNC(self, SEL_COMMAND, self.ID_2, 
            MyClass.onCmdPrintMsg)                  

        FXButton(self, 'Button 1', None, self, self.ID_1)
        FXButton(self, 'Button 2', None, self, self.ID_2)
         
    def onCmdPrintMsg(self, sender, sel, ptr):              
        if SELID(sel) == self.ID_1:
            print 'Button 1 was pressed.'
        elif SELID(sel) == self.ID_2: 
            print 'Button 2 was pressed.'
        return 1

The previous example starts by generating a list of IDs for use in the derived class. Since a widget has a specific target, the ID of a widget does not have to be globally unique; it needs to be unique only within the target’s class and base classes. To handle this numbering automatically, the convention is to define ID_LAST in each class. A derived class should begin its numbering using the value of ID_LAST defined in its base class. In addition, a derived class should define its own ID_LAST as the last ID in the derived class. A class that derives from the derived class will then be able to make use of that ID to begin its numbering. ID_LAST should not be used by any widget. The only purpose of ID_LAST is to provide an automatic numbering scheme between classes.

The example continues by constructing a message map by adding entries using the FXMAPFUNC function. In this example, when a message of type SEL_COMMAND and an ID of ID_1 or ID_2 is received, the script calls the onCmdPrintMsg method.

The two button widgets have their target set to self (MyClass). However, when each widget sends a message, the widget sends a different message ID and the message handler checks the ID to determine who sent the message. For example, if the user clicks the first button, the button sends a (ID_1, SEL_COMMAND) message to MyClass. The class’s message map routes that message to the onCmdPrintMsg method. The onCmdPrintMsg method checks the ID of the incoming message and prints Button 1 was pressed.

It is important that your message handlers return the proper value to ensure that the GUI is kept up-to-date. Returning a 1 in a message handler tells the toolkit that the message was handled. In turn, if a message is handled, the toolkit assumes that something may have changed that requires an update, and the toolkit initiates a GUI update process. Returning a 0 in a message handler tells the toolkit that the message was not handled; therefore, the toolkit does not initiate a GUI update process.

Messages are normally sent by the GUI infrastructure as the result of some interaction in the GUI. However, you can send a message directly to an object by calling its handle method. The handle method takes three arguments: sender, selector, and userData. The sender is generally the object that is sending the message. The selector is made up of the message ID and the message type. You can use the MKUINT function to create a selector, for example, MKUINT(ID_1, SEL_COMMAND). The user data must be None since this feature is not supported in the ABAQUS GUI Toolkit.

GUI updating is initiated automatically by the ABAQUS GUI Toolkit when there are no more events to be handled, usually when the GUI is idle and waiting for some user interaction. During the automatic GUI update process, each widget sends a SEL_UPDATE message to its target asking to be updated. In this way the GUI is constantly polling the application state to keep itself up-to-date.

For example, during automatic GUI updating, a check button sends an update message to its target. The target checks some application state and determines whether or not the check button should be checked. If the button should be checked, the target sends back an ID_CHECK message; otherwise, it sends an ID_UNCHECK message.

Widgets in the toolkit are bi-directional; that is, they can be in either a push state or a pull state.

In a typical GUI application you will want to do the following:

A data target acts as a bi-directional intermediary between some application state and GUI widgets. More than one widget can be connected to a data target, but a data target acts on only one piece of application state. When the user uses the GUI to change a value, the application state monitored by the data target is updated automatically. Conversely, when the application state is updated, the widget connected to the data target is updated automatically.

As described in “Automatic GUI updating,” Section 6.5.5, widgets can be in a push state or a pull state.

A data target works in one of two modes: value or option. The examples in the previous section described the value mode. You use the value mode when the actual value of some data is of interest. In contrast, you use the option mode when you require a selection from many items and the value is not of particular importance.

For data targets operating in the option mode with a widget in the push state, the behavior is similar to the value mode described in the previous section. When the user clicks a button, the button sends an (ID, SEL_COMMAND) message to its target. In turn, the target responds by sending the sender a message requesting it to update the data target’s data to the value of the sender’s message ID.

For data targets operating in the option mode with a widget in the pull state, the behavior is slightly different from the value mode described in the previous section. During a GUI update the data target sends either a check or uncheck message back to the sender, depending on whether the sender’s ID matches the value of the data target’s data.

For example, Figure 6–5 illustrates a data target operating in the option mode with three radio buttons in the pull state. Suppose that the value of the data being monitored by the data target is 13 and the message IDs of the radio buttons are 2, 13, and 58, respectively. The sequence is as follows:

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 Chapter 5, “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,” Section 6.5.6.

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:

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:

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)

Keywords are used in the GUI by setting them as the targets of widgets. The AFXDataDialog class takes a mode as one of its constructor arguments. The dialog box uses the mode provided in the constructor to access the keywords stored in the mode. In addition, the dialog box uses the keywords as targets of widgets in the dialog.

In addition to a target, a widget also has a message ID. It is important that the appropriate ID be set for the keyword to operate in the proper mode: value or option. For more information, see “Data targets,” Section 6.5.6. In most cases a value of zero should be used for the message ID; a value of zero indicates that the keyword should operate in value mode. The table below summarizes the message ID usage with keywords, and the following sections give examples for each type of keyword.

The following statements illustrate the use of Boolean, integer, float, and string keywords:

# Boolean keyword
#
FXCheckButton(self, 'Show node labels', mode.nodeLabelsKw, 0)
        
# Integer keyword
#
AFXTextField(self, 8, 'Number of CPUs:', mode.cpusKw, 0)
            
# Float keyword
#
AFXTextField(self, 8, 'Radius:', mode.radiusKw, 0)  
            
# String keyword
#
AFXTextField(self, 8, 'Name:', mode.nameKw, 0)

Symbolic constants provide a way to specify choices for a command argument that make the command more readable. For example, there are three choices for the renderStyle argument in display options commands. We could number these choices using integer values from 1 to 3. However, using integer values would result in a command that is not very readable; for example, renderStyle=2. Alternatively, if we define symbolic constants for each choice, the command becomes more readable; for example, renderStyle=HIDDEN. Internally, symbolic constants contain an integer ID that can be accessed via its getId() method. Symbolic constants can be used in both the GUI and kernel processes. Typically you should create a module that defines your symbolic constants and then import that module into both your kernel and GUI scripts.

You can import the SymbolicConstant constructor from the symbolicConstants module. The constructor takes a single string argument. By convention, the string argument uses all capital letters, with an underscore between words, and the variable name is the same as the string argument. For example,

 from symbolicConstants import SymbolicConstant
 AS_IS = SymbolicConstant('AS_IS')

In the case of symbolic constant keywords, you can use a value of zero or the value of the ID of a symbolic constant for the message ID. Symbolic constants have a unique integer ID that is used to set the value of symbolic constant keywords along with a string representation that is used in the generation of the command. To access the integer ID of a symbolic constant, use its getId method.

If the keyword is connected to a list or combo box widget, you should use a value of zero for the ID in the widget constructor. The AFXList, AFXComboBox, and AFXListBox widgets have been designed to handle symbolic constant keywords as targets. When items are added to a list or combo box, a symbolic constant’s ID is passed in as user data. These widgets react by setting their value to the item whose user data matches the value of their target, as opposed to setting their value to the item whose index matches the target’s value. The following example illustrates how a combo box can be connected to a symbolic constant keyword:

combo = AFXComboBox(hwGb, 18, 4, 'Highlight method:', 
    mode.highlightMethodHintKw, 0)
combo.appendItem('Hardware Overlay', HARDWARE_OVERLAY.getId())
combo.appendItem('Software Overlay', SOFTWARE_OVERLAY.getId())
combo.appendItem('XOR', XOR.getId())
combo.appendItem('Blend', BLEND.getId())

If the keyword is connected to a radio button, you should use the ID of the symbolic constant that corresponds to that radio button for the message ID. Since the ID of all symbolic constants is greater than zero, this tells the keyword to operate in option mode. The following example illustrates how symbolic constant keywords can be used with radio buttons:

from abaqusConstants import *
...
# Modeling Space
#
gb = FXGroupBox(self, 'Modeling Space', 
    FRAME_GROOVE|LAYOUT_FILL_X)
FXRadioButton(gb, '3D', mode.dimensionalityKw, 
    THREE_D.getId(), LAYOUT_SIDE_LEFT)
FXRadioButton(gb, '2D Planar', mode.dimensionalityKw, 
    TWO_D_PLANAR.getId(), LAYOUT_SIDE_LEFT)
FXRadioButton(gb, 'Axisymmetric', mode.dimensionalityKw, 
    AXISYMMETRIC.getId(), LAYOUT_SIDE_LEFT)

In the case of tuple keywords, a value of zero for the message ID indicates that the entire tuple will be updated. For example, you can use a single text field to collect X-, Y-, and Z-inputs from the user. In this case the comma-separated string entered by the user is used to set the entire value of the tuple keyword. For example, if you define a tuple keyword as follows:

self.viewVectorKw = AFXTupleKeyword(cmd, 'viewVector', TRUE, 3, 3)

AFXTextField(self, 12, 'View Vector (X,Y,Z)', mode.viewVectorKw, 
    0, AFXTEXTFIELD_FLOAT)

AFXTextField(self, 4, 'X:', mode.viewVectorKw, 1)
AFXTextField(self, 4, 'Y:', mode.viewVectorKw, 2)
AFXTextField(self, 4, 'Z:', mode.viewVectorKw, 3)

The AFXTableKeyword must be connected to a table widget. This type of keyword will result in a command argument that is a tuple of tuples. The values in a table keyword can be Ints, Floats, or Strings.

The default minimum number of rows is 0, and the default maximum number rows is –1, indicating that the number of rows is unlimited. Tables can vary in size because the user can add or delete rows; as a result, you usually specify the defaults for the minimum and maximum number of rows. For example, to generate a command that creates XY data, you can define the following keywords in the form

self.cmd = AFXGuiCommand(self, 'XYData', 'session')
self.nameKw = AFXStringKeyword(self.cmd, 'name', TRUE)        
self.dataKw = AFXTableKeyword(
    self.cmd, 'data', TRUE, 0, -1, AFXTABLE_TYPE_FLOAT)

table = AFXTable(vf, 6, 3, 6, 3, 
    form.dataKw, 0, AFXTABLE_NORMAL|AFXTABLE_EDITABLE)

The AFXObjectKeyword has a variable name for its value. In most cases you use an AFXObjectKeyword in a command that is preceded by some setup commands. For example,

p = mdb.models['Model-1'].parts['Part-1']
session.viewports['Viewport: 1'].setValues(displayedObject=p)

A defaults object can be used to restore the values of the keywords in a command to their default values when the user presses the Defaults button in the dialog box. You can register a defaults object with a command as follows:

self.registerDefaultsObject(cmd, 'session.defaultGraphicsOptions')

If no defaults object is specified, the command uses the default values specified in the keyword's constructor when the user presses the Defaults button in the dialog box.