How to add new types of Parts to Stacksmith
It is probably easiest to just take an existing part type and duplicate and rename all its classes. I recommend using "button" or "timer".
Every part needs to have a unique one-word "type" string that can be used for its part type in the XML and for distinguishing it from other part types when listing and accessing parts via other object descriptors than just "part". So pick one now. For example, buttons have "button" and movie players have "moviePlayer".
When should I add a new part vs. a new style of an existing part
Stacksmith and HyperCard before it have a long history of subsuming what would be distinct control types as styles of one part. The main criterion applied here should be what it feels like to the user. Implementation under the hood should not dictate breaking out a new kind of button into something else than a button style. But conversely, just because some objects behave like re-painted versions of each other should not mean they should be the same part type. A good example of this are sliders and scroll bars, which are used for completely different things, so should be different part types, not just styles of the same scale part.
A good indicator of a part that should be broken out is often if it suddenly needs to add properties to a part type that have nothing to do with the other part styles. Like the minValue/maxValue properties on SuperCard's scrollbar button style, that none of the others would need. A good example of integrating a completely different control as a style are simple list fields. Users think of these as lists, and write lists into text fields, then think they might want to be able to select a line, so turn on autoSelect and implicitly get a platform-native table view. However, it's also an edge case, as multi-column table views exceed this metaphor and might call for a different implementation.
Registering instructions for a part type
All object descriptor syntax is defined by host function tables in
Next define the corresponding functions (and their prototypes) in
There are corresponding
Now that you have the instruction functions, register them with the instruction table lower in the file by adding
Registering syntax for a part type
Once you have defined the instruction functions and the symbolic constants you'll refer to them with, you need to define the actual Hammer syntax that scripters will use to refer to your part. A typical object descriptor looks like
Registering new identifiers
First, you must make sure that any new identifiers you need are defined in
To just define a single identifier, say "frog", use
Where the first parameter is the constant that will be used by you in host code (the "token identifier type"). The second parameter is the actual string the user will use in a Hammer script. This string must be all lower-case. Some older xTalks permitted short forms for identifiers as synonyms that can be typed more quickly. It is generally not recommended to add short forms (users read scripts more often than they write, so they should rather use autocompletion to write the longer identifiers than write a short form that they have to mentally expand when reading every time), but should you need to, you can define a synonym using the
This declares a new token
Note that this is not a general synonym specification mechanism. Tokens declared as synonymous like this will not be converted back into their short form by the parser. There is no way you can match EFrgIdentifier alone in some spots once it is a synonym for another token. It is recommended to define other synonyms simply by providing two kinds of syntax. This mechanism is simply there to support classic HyperTalk synonyms like
Registering the actual syntax
The actual syntax for an object descriptor is defined in
There are six entries for each part type's syntax: "card typename x", "background typename x", "number of card typenames", "number of background typenames" and the shorter "typename x" equivalent to "card typename x", and "number of typenames" equivalent to "number of card typenames". Just duplicate the entries and the array will resize to accomodate them.
Creating the actual class that implements a part
There are generally two classes. The cross-platform class, e.g.
Once you have the class, you have to make the platform-specific
Where "button" here is the unique type string you picked for your part type.
Adding UI for creating your part
Currently, there is no standard mechanism for creating new parts. You'll have to duplicate the CStackMac's
|Last Edited: 2015-03-01 Visitors: 1737|