BaKoMa TeX
Dialog Customization

This description is related only for BaKoMa TeX 11.0 or later.

Dialogs

wxPS is new format of dialogs and toolbars available beginning from BaKoMa TeX 10.80 (April 2015)

In short, wxPS is similar to wxXMLResource, but it keeps dialog templates in PostScript dictionary instead of XML.

Simple dialog may be defined like following:

<</Type /Dialog
  /Label (Dialog with two buttons)
  /Sizer 1
  /Childs [
    <</ID 1 /Type /Button /Label (OK) /Tip (Click to approve action.)>>
    <</ID 2 /Type /Button /Label (Cancel) /Tip (Click to decline action.)>>
  ]
>>

Such dictionaries may be accepted directly by 'dialog' and 'setcontrolbar' operators instead of strings with windows templates.

In one side, such dictionaries may be kept in PostScript resources. In another side, such dictionaries may be created dynamically using postscript code. Both ways may be freely combined. Some dialogs may be compiled from predefined components. These components may be made up according to some conditions.

Dialog definition

Dialog is defined as PostScript dictionary with a keys:

KEY	TYPE	VALUE/DESCRIPTION
/Type	Name	/Dialog
/Name	Name	[Optional] uniqual key identifying dialog.
/Label	String	[Recommended] Label of dialog (caption in title)
/Mode	Integer	[Optional] 1 - QuickClose, 2 - supress nested events, 4 - OAC
/Style	Integer	[Optional] dialog styles (see wxDialog styles)...
/Pos	[Int Int]	[Optional] [#x #y] position of dialog relative to parent window, if missed dialog will be centered
/Size	[Int Int]	[Optional] [#width #height] if missed '/Sizer' may determine the size dynamically.
/Icon	String	[Optional] icon for left top corner fo dialog in titlebar.
/Font	Dict	[Optional] << /Name (facename) /Size #pointsize >>
/BackgroundColor	String	[Optional] Default dialog background color.
/ForegroundColor	String	[Optional] Default dialog foreground color.
/Childs	Array	array of controls, sizers, notebooks whose will be appeared on dialog.

NOTE: Dialog can include also anu Sizer functionality as described below.

Dialog Childs

Childs is array of following elements:

TYPE	VALUE/DESCRIPTION
Integer	any integer adds space, value >= 1000 - stretchable space.
Control dictionary	Control Dictionary must include '/Type' key which defines type of control.
Sizer dictionary	/Type must be /Sizer.
Notebook dictionary	/Type must be /Notebook, or /Choicebook, or /Listbook, or /Simplebook.
CollapsiblePane dictionary	/Type must be /CollapsiblePane.

Sizer Dictionary

Sizer dictionary keys may be merged with dictionaries of dialog root, notebook panel, and collapsible panel.

Key	TYPE	VALUE/DESCRIPTION
/Type	Name	/Sizer (It must be only when sizer do not shared with dialog, notebook page, or collapsible panel.
/Sizer	Integer	class of sizer: 0 - vertical sizer 1 - horizontal sizer 2 - horizontal sizer with border which may be signed by Label 3 - vertical sizer with border which may be signed by Label 100+columns - Grid sizer 200+columns - Flex Grid Sizer.
/Label	Integer	[Optional] may be used by sizers 2 and 3
/Flags	Integer	[Optional] sizer flags.
/Border	Integer	[Optional] sizer border.
/Prop	Integer	[Optional] sizer proportions.
/ChildFlags	Integer	[Optional] default of sizer flags for all childs.
/ChildBorder	Integer	[Optional] default of sizer border for all childs.
/ChildProp	Integer	[Optional] default of sizer proportions for all childs.
/Childs	Integer	[ array of of controls, sizers, and notebooks ]

NOTE: In order to minimize dictionary nesting Sizer dictionary may be merged together with dialog root dictionary, notebook pages, and CollapsiblePane pane.

Notebook Dictionary

Key	TYPE	VALUE/DESCRIPTION
/Type	Name	/Notebook, or /Choicebook, or /Listbook, or /Simplebook.
/ID	Integer	[Optional]
/Style	Integer	[Optional] dialog styles (see wxDialog styles)...
/Pos	[Int Int]	[Optional] [#X #y]
/Size	[Int Int]	[Optional] [#width #height] if missed '/Sizer' may determine the size dynamically.
/BackgroundColor	String	[Optional] Default notebook background color.
/ForegroundColor	String	[Optional] Default notebook foreground color.
/Childs	Array	array of Notebook page Dictionaries.

Notebook Page Dictionary

Key	TYPE	VALUE/DESCRIPTION
/Label	String	label of Notebook panel which is appeared on tab control.
/BackgroundColor	String	[Optional] Default notebook panel background color.
/ForegroundColor	String	[Optional] Default notebook panel foreground color.

NOTE: May be used any Sizer keys, including Childs

CollapsiblePane Dictionary

Key	TYPE	VALUE/DESCRIPTION
/Type	Name	/CollapsiblePane
/ID	Integer	[Optional]
/Label	String	label which will be visible when pane is collapsed.

NOTE: Must include sizer keys together with Childs

Control Dictionary

Key	TYPE	VALUE/DESCRIPTION
/Type	Name	list of controls see below.
/ID	Integer	integer which will be passed to handler (keep them uniqual for all tools and controls in one toolbar)
/Style	Integer	control dependent style.
/Tip	Integer	[Optional] string, tooltip which will be displayed when mouse is over control.
/Pos	Integer	[Optional] [#x #y] - adjusts position of control.
/Size	Integer	[Optional] [#width #height] - adjusts size of control.
/BackgroundColor	String	[Optional] Default control background color.
/ForegroundColor	String	[Optional] Default control foreground color.
/Action	Integer	[Optional] proc|name|dict, it is command or option attached to control (See Actions)

Below is list of controls supported by dialogs:

TYPE	DESCRIPTION, additional keys and styles
/Button	Classical button with text specified by additional /Label key /Label - string, text which will be shown on button. /Style key accepts /WXBU_ flags: LEFT - Left-justifies the label. Windows and GTK+ only. TOP - Aligns the label to the top of the button. Windows and GTK+ only. RIGHT - Right-justifies the bitmap label. Windows and GTK+ only. BOTTOM - Aligns the label to the bottom of the button. Windows and GTK+ only. EXACTFIT - By default, all buttons are made of at least the standard button size, even if their contents is small enough to fit into a smaller size. This is done for consistency as most platforms use buttons of the same size in the native dialogs, but can be overridden by specifying this flag. If it is given, the button will be made just big enough for its contents. Notice that under MSW the button will still have at least the standard height, even with this style, if it has a non-empty label. NOTEXT - Disables the display of the text label in the button even if it has one or its id is one of the standard stock ids with an associated label: without using this style a button which is only supposed to show a bitmap but uses a standard id would display a label too. BORDER_NONE - Creates a button without border.
/CheckBox	is a labelled box which by default is either on (checkmark is visible) or off (no checkmark). /Label - [Optional] string, label (comment) at right of checkbox. /Style key accepts /WXCHK_ flags: 2STATE - Create a 2-state checkbox. This is the default. 3STATE - Create a 3-state checkbox. Not implemented in wxGTK built against GTK+ 1.2. ALLOW_3RD_STATE_FOR_USER - By default a user can't set a 3-state checkbox to the third state. It can only be done from code. Using this flags allows the user to set the checkbox to the third state by clicking. ALIGN_RIGHT -Makes the text appear on the left of the checkbox. NOTE: It should be used together with /Action pointing on BooleanOption
/TextCtrl	A text control allows text to be displayed and edited. (wxTextCTrl) /Label - [Optional] string, text which will be inside control at creating. /Style key accepts /WXTE_ flags (suitable for toolbar): READONLY - The text will not be user-editable. PASSWORD - The text will be echoed as asterisks. LEFT - The text in the control will be left-justified (default). CENTRE - The text in the control will be centered (currently wxMSW and wxGTK2 only). RIGHT - The text in the control will be right-justified (currently wxMSW and wxGTK2 only). NOTE: It should be used together with /Action pointing on StringOption
/Choice	A choice control is used to select one of a list of strings. (wxChoice) /Label - string, will be treated by the control in special way. /Style key accepts /WXCB_ flags: SORT - Sorts the entries alphabetically NOTE: It should be used together with /Action pointing on ListOption
/BitmapButton	Bitmap button with image specified by additional /Icon key /Icon - string, name of icon which will be displayed on button. /Style key accepts /WXBU_ flags: LEFT - Left-justifies the bitmap label. TOP - Aligns the bitmap label to the top of the button. RIGHT - Right-justifies the bitmap label. BOTTOM - Aligns the bitmap label to the bottom of the button. Note: that the EXACTFIT style supported by Button is not used by this class.
/StaticText	A static text control displays one or more lines of read-only text. /Label - string, text which will be shown.
/StaticBitmap	A static bitmap control displays a bitmap. /Icon - string, name of icon which will be displayed.
/HyperLink	Label looking like to hyperlink, at click automatically open Url page. /Label - string, shown string. /Url - string, URL which will be opened at clicking on the control.
/StaticBox	/Label - string, text which will mark the box at left top corner.
/BKMButton	/Label - string, will be treated by the control in special way.
/RadioButton	/Label - [Optional] string, label (comment) at right of radiobutton.
/ComboBox	/Label - [Optional] string, text which will be inside control at creating.
/ListBox	No additional keys.
/TreeCtrl	No additional keys.
/Console	Special Control.
/CommandLinkButton	It is like to button, but may include long comment. /Label - string, Basic label. /Note - string, long comment displayed in smaller size.
/HtmlListBox	HTML code may be added to items.
/HtmlWindow	Window displaying HTML. /LoadFile - string, load HTML from local file. /LoadPage - string, load HTML from file (url is available). /SetPage - string, HTML body from styring.
/ColourPicker	Handled preciselly as TextCtrl, which includes colour name or specification. User see button with colour rectangle, clicking displays colour pickign dialog.

Loading wxPS dialogs from resources

wxPS dialogs or standard components of dialogs may be kept as PostScript Resources.
Standard place for keeping dialogs is BaKoMa\Dialog\wxPS
This folder is good source for samples.

wxPS resources are programs building dictionaries. In this reason, they may include some logic for different cases.

For example (standard buttons should have differnt order on different platforms):

One interesting example is in OKCancel.wxps:

%!PS-Adobe-3.0 Resource-Category
%%BeginResource: Dialog (About)
%%Version: 1.000
%%Copyright: (C) 2015, Basil K. Malyshev. All Rights Reserved.
%%EndComments

/OKCancel
<</Type /Sizer
  /Sizer 1 
  /Flags /WXSIZER_{ALIGN_RIGHT LEFT RIGHT TOP} Flags % Adds Right alignment of control buttons.
  /Childs [
     <</Type /Button /Label (OK) /ID 1 /Action /OK /Style /WXBU_/Default Flags 
	/Tip (Close the dialog with an action.) /Border 0>>
     <</Type /Button /Label (Cancel) /ID 2 /Action /Cancel 
	/Tip (Closes the dialog withot an action.) /Border 0>>
     statusdict /Environment get /Win32 ne {exch} if % change order for /MacOS and /Linux
     /WXSIZER_{STD_BORDER} Flags exch
  ]
>> /Dialog defineresource pop

%%EndResource

%%EOF

Take attention on bold line. Under Windows and OSX/Linux different order of [OK] and [Cancel] buttons are used. This line swaps [OK] and [Cancel] buttons under proper operating systems.

This component may be used (see bold line), for example, in following simple dialog:

<<
  /Type /Dialog
  /Label (Insert RAW TeX Command)
  /Sizer 0 /Flags /WXSIZER_{LEFT RIGHT TOP} Flags % (additional spacer at bottom is required)
  /Border /WXSIZER_{STD_BORDER} Flags % Default is '6', but may be changed. 
  /Childs [
    <</Type/Sizer/Sizer 1 
      /Flags /WXSIZER_{ALIGN_CENTER_VERTICAL LEFT RIGHT TOP} Flags % Adds vertical alignment of elements.
      /Childs [
        <</Type /StaticText /Label (TeX Command:) /ID 5 >>
        <</Type /TextCtrl   /Label (\\) /Size [120 12] /ID 4 /Tip (Enter TeX command to insert) >>
      ]
    >>
    /OKCancel /Dialog findresource
    /WXSIZER_{STD_BORDER} Flags 2 mul % 12 % Already mentioned "spacer at bottom".
  ]
>>