GCA Character Sheet
From GCAWiki
GCA Character Sheet (also referred to as Character Sheet and Sheet) is a file format for defining a Visual Basic Script applet for GCA which is used to provide formatted output of characters.
Contents |
File format and structure
Basic file skeletons
The most basic file skeleton is:
'VBScript 'The line above must be the very first line of the file. '' ' Called by GCA to run (print/preview/export) the sheet. ' ' This subroutine *must* exist. '' Sub Main() 'your sheet code here End Sub
The same w/ the sheet options routine:
'VBScript 'The line above must be the very first line of the file. '' ' Called by GCA to populate the Character Sheet Options window and enumerate ' the Options object. ' ' If you want users to be able to configure this sheet via the Character Sheet ' Options window in GCA, this subroutine *must* exist. '' Sub CharacterSheetOptions() 'your options code here End Sub '' ' Called by GCA to run (print/preview/export) the sheet. ' ' This subroutine *must* exist. '' Sub Main() 'your sheet code here End Sub
Character interface
Character data is interfaced via the Character (object), which is exposed to sheets by the Char variable, which is per character and references the character in the currently active character tab, and the Chars variable, which is a collection of all open characters.
[tmedwards: need to make this whole section better, it's kinda lacking at the moment]
Interface hierarchy
[tmedwards: should eventually list some of the newer collections as well]
| Char or Chars(i) <Character (object)> Use: base character data, also the entry-point for all other character data collections and objects | ||||||
| ↓ | ↓ | ↓ | ↓ | |||
| Items <SortedItemCollection (object)> Use: single "all traits" collection | ItemsByType <SortedItemCollection (object)> Use: multiple "per trait type" collections | Body <Body (object)> Use: body locations | Campaign <CampaignInfo (object)> Use: base campaign information | |||
| ↓ | ↓ | ↓ | ||||
| Item <Item (object)> Use: character traits | Item <Item (object)> Use: character traits | Log <LogEntry (object)> Use: campaign log | ||||
Printer interface
VSPrinter tips
[tmedwards: discuss tips here, yadda yadda]
See Also: For further information about VSPrinter itself, visit ComponentOne's VsView 8.0 online documentation or download the VsView 8.0 PDF documentation. As noted, the docs are for VsView 8 not 7, which is the version that GCA uses, however, it still provides a good foundation to learn from.
Known VSPrinter issues/bugs to watch out for
[tmedwards: discuss bugs/pitfalls & the work-arounds here -- I've seen things you people wouldn't believe.]
NewPage & CurrentX/CurrentY
After a call to NewPage, some VSPrinter internal settings can occasionally contain bogus values. Setting CurrentX & CurrentY, even if they themselves have sane values, will also set the afflicted internals to sane values, so it's recommended that you always set both CurrentX & CurrentY after a call to NewPage.
Practical examples
[tmedwards: show a variety of practical/real-world sheet examples here]
Tips
GCA Logging window
Check your GCA Logging window (View > Logging Window) often while testing/using the applets you're developing to catch errors.
Explicit variable declaration
It is strongly suggested that you use the VBScript Option command to enable Explicit mode in the VBScript engine. You should add it near the top of your applet file, just after the VBScript comment, for example:
'VBScript 'The line above must be the very first line of the file. 'force explicit variable declaration Option Explicit
Enabling Explicit mode will make the VBScript engine throw an error if you attempt to use a variable without declaring it first. The reasons that you'd want to do this are:
- So you don't have issues with misspelled variable names.
- So you don't accidentally use a reserved word as a variable name. This can really haunt you if you're not paying attention, as VBScript will happily let you overwrite built-ins with the default implicit declaration, which it won't if you explicitly declare your variables with Dim/ReDim -- it'll throw an error instead.
Hexadecimal values
When using hexadecimal values, always use the &H& format (e.g. &H000001&) and never the &H format (&H000001), unless you know you need the latter. The reason being is that when using hexadecimal values in VBScript, values greater than or equal to 32768 are considered to be signed integers, unless you append an ampersand to them, in which case they're considered unsigned integers. So, if you intend to use hexadecimal values as flags, color values, or any other case where they should definitely be considered unsigned integers, always use the &H& format.
