Documentation

Pashua 0.9.4.7 Documentation

Pashua 0.9.4.7 Documentation

iii

Table of Contents1. Introduction ................................................................................................................................................... 1

1. What is Pashua? ................................................................................................................................... 12. How to use Pashua ............................................................................................................................... 1

2.1. Creating a dialog ....................................................................................................................... 12.2. Getting values back from Pashua .............................................................................................. 12.3. Using the example scripts ......................................................................................................... 1

2. The window configuration ........................................................................................................................... 21. Basic configuration syntax rules .......................................................................................................... 2

1.1. A first example .......................................................................................................................... 32. Window attributes ................................................................................................................................. 43. Element type: button ........................................................................................................................ 64. Element type: cancelbutton .......................................................................................................... 75. Element type: checkbox .................................................................................................................... 86. Element type: combobox .................................................................................................................... 97. Element type: date ........................................................................................................................... 118. Element type: defaultbutton ...................................................................................................... 139. Element type: image ......................................................................................................................... 1410. Element type: openbrowser ......................................................................................................... 1611. Element type: password ................................................................................................................ 1712. Element type: popup ....................................................................................................................... 1913. Element type: radiobutton ......................................................................................................... 2014. Element type: savebrowser ......................................................................................................... 2215. Element type: text ......................................................................................................................... 2416. Element type: textbox .................................................................................................................. 2617. Element type: textfield ............................................................................................................. 28

3. Topics .......................................................................................................................................................... 301. Unicode and text encodings ............................................................................................................... 302. Localization ......................................................................................................................................... 313. Dynamic configuration strings ........................................................................................................... 314. Building “real” applications with Pashua ........................................................................................... 32

4. FAQ ............................................................................................................................................................. 341. How do I display 2 or more windows one after another? .................................................................. 342. When will Pashua support multiple checkboxes / radiobuttons / …? ................................................ 343. May I distribute applications based on Pashua? ................................................................................ 344. How can I hide the dock icon? .......................................................................................................... 345. Are there any tutorials on using Pashua? ........................................................................................... 346. WTF does “Pashua” mean? ................................................................................................................ 35

5. Version history ........................................................................................................................................... 36

iv

List of Tables2.1. Window attributes ...................................................................................................................................... 42.2. Attributes for elements of type button .................................................................................................. 62.3. Attributes for elements of type cancelbutton .................................................................................... 72.4. Attributes for elements of type checkbox ............................................................................................. 82.5. Attributes for elements of type combobox ............................................................................................. 92.6. Attributes for elements of type date ..................................................................................................... 112.7. Attributes for elements of type defaultbutton ................................................................................ 132.8. Attributes for elements of type image .................................................................................................. 142.9. Attributes for elements of type openbrowser .................................................................................... 162.10. Attributes for elements of type password .......................................................................................... 182.11. Attributes for elements of type popup ................................................................................................. 192.12. Attributes for elements of type radiobutton .................................................................................. 212.13. Attributes for elements of type savebrowser .................................................................................. 222.14. Attributes for elements of type text ................................................................................................... 242.15. Attributes for elements of type textbox ............................................................................................ 262.16. Attributes for elements of type textfield ....................................................................................... 283.1. Table of supported encodings ................................................................................................................. 30

v

List of Examples2.1. Example window ...................................................................................................................................... 62.2. Example button ...................................................................................................................................... 72.3. Example cancelbutton ....................................................................................................................... 82.4. Example checkbox ................................................................................................................................. 92.5. Example combobox ............................................................................................................................... 112.6. Example date ........................................................................................................................................ 132.7. Example defaultbutton ................................................................................................................... 142.8. Example image ...................................................................................................................................... 152.9. Example openbrowser ........................................................................................................................ 172.10. Example password ............................................................................................................................. 192.11. Example popup .................................................................................................................................... 202.12. Example radiobutton ...................................................................................................................... 222.13. Example savebrowser ...................................................................................................................... 232.14. Example text ...................................................................................................................................... 262.15. Example textbox ............................................................................................................................... 272.16. Example textfield ........................................................................................................................... 29

1

Chapter 1. Introduction1. What is Pashua?

Pashua ist a tool for creating native Aqua dialog windows on Mac OS X. It can be invoked from the shell andtherefore is particularly useful for creating GUIs from programming languages that do not offer graphic userinterfaces natively, for instance Perl, PHP or Ruby.

Pashua was written by Carsten Blüm and released as donationware (free to use, but donations welcome).Pashua’s website is www.bluem.net/en/mac/pashua/ [http://www.bluem.net/en/mac/pashua/]

2. How to use Pashua

2.1. Creating a dialog

Basically, Pashua is used like many command-line programs: you call it from your application, pass the pathto a configuration file as argument (or let Pashua read the configuration string from stdin by passing - asthe filename) and, optionally, add some other arguments (to be precise, there is only one at the moment: -e,to define the encoding—see the section on encodings [30]). Pashua will display a dialog that is createdaccording to the description in the configuration file / string [2], while typically your application willwait for the dialog to close.

2.2. Getting values back from Pashua

Pashua will quit when the user clicks the “OK” button (or enters return), clicks the “Cancel” button orhits Escape (provided there is a cancelbutton [7] in the window). In the first case, for every elementdefined in the config string, the value is returned. Let’s say, the window contains a textfield [28] namedcity that holds the string “Hamburg”, then the result (written to stdout by Pashua) would contain a linecity=Hamburg. Your application could read Pashua’s output and parse each of the lines to get the valuefor the element.

In the latter case (“Cancel” button), no values are returned, except the cancel button itself, which is returnedas 1. This means: if your configuration string contains a definition like cb.type = cancelbutton andthe button will be pressed, then Pashua’s output will contain cb=1.

2.3. Using the example scripts

However, you don’t have to deal with calling Pashua and interpreting the result manually—the examplescripts included in the distribution do that for you. In most of these scripts, you only have to pass theconfiguration string to a function or method and that’s it.

Of course, if you have special needs or don’t like the way the example scripts work, you are free to write yourown code; it’s completely up to you.

http://www.bluem.net/en/mac/pashua/

http://www.bluem.net/en/mac/pashua/

2

Chapter 2. The window configurationAs said above, the dialog window to be created is described in a configuration file or string. For this purpose,Pashua uses a very simple and light-weight configuration syntax which describes the GUI elements todisplay, their properties (e.g. default values) und their order in the window.

The following part of the documentation will describe the basics of the configuration syntax, the GUIelements available and the attributes that can be set for these elements.

1. Basic configuration syntax rules

Pashua’s configuration syntax is pretty simple. Basic Rules are:

• Empty lines are ignored.

• Lines starting with the hash symbol # are treated as comments—like in Perl, Shell, PHP, Python, Ruby,Tcl, probably a few other languages and many Unix configuration files.

• Every command must be on its own line.

• Every command consists of: a string (called “identifier” below), followed by an equal sign =, followed byanother string. The only exception to this rule is: a line consisting of nothing but a hyphen - will create ahorizontal separator line at the appropriate position in the window.

• Every “identifier” must consist of a unique name for a GUI element (any ASCII string, preferablyall lowercase—please note that window attributes must use an asterisk * as that name, see windowattributes [4]), followed by a period, followed by an attribute name. Each type of GUI element hasits own set of allowed attributes, and a large part of this documentation deals with those properties. Thename for the GUI element is not only a string that is used internally by Pashua, but it will also be usedfor returning values to the calling script / application, so you should regard these names as some sort ofvariable names.

• Anything after the equal sign is considered the value.

• Attributes and the names of the element types are case-sensitive.

• Leading and trailing whitespace is ignored for both the identifier and the value. For instance, for Pashua thefollowing two lines would be the same:

name.label=Please enter your name name.label = Please enter your name

• The GUI elements are displayed in the order in which they appear in the config string. The only exceptionto this rule are buttons: the default button is always in the lower right corner of the window, the cancelbutton (if defined) is located left to the default button and any other buttons will appear in the lower leftcorner, from left to right, in the order they were defined.

The window configuration

3

• You don’t have to specify attributes in consecutive blocks. You can add as many empty lines as you like,and you could even mix up commands of different elements.

• When an attribute is specified more than once, the last one will be used:

x.label = Label Ax.label = Label Bx.label = Label C

… would result in the element being labeled with “Label C”. An exception to this rule is option, whichis used to set values for radiobuttons [20], combo boxes [9] and popups [19] and which maybe used in multiple commands.

1.1. A first example

Let’s have a look at a simple example:

# Add a text fieldtx.type = textfieldtx.label = Example textfieldtx.default = Textfield contenttx.width = 310

These lines would simply mean:

• Line 1: A comment

• Line 2: The window should contain a textfield that we simply call “tx” to be able to address it in the nextlines and to get the returned value later on.

• Line 3: The textfield should be titled “Example textfield”.

• Line 4: Set the initial text displayed in the textfield to “Textfield content”.

• Line 5: Set the textfield’s width to 310 Pixels.

Note that the above lines would suffice to display the following window:


4

Or, if you like to keep things really simple, passing …

tx.type = textfield

… to Pashua would result in this window:

2. Window attributes

Window attributes are defined similar to element attributes. The only difference (apart from the fact thatof course windows have other attributes than, let’s say, textfields [28]) is the fact that you don’t haveto specify an element name before the attribute, but simply an asterisk, for instance *.title = Mywindowtitle

Table 2.1. Window attributes

Name Purpose Required Default Since version

title Sets the window title No Pashua 0.9.3 (was calledwindowtitlebefore)


5

Name Purpose Required Default Since version

transparency Sets the window’stransparency,decimal value from0 (invisible) to 1(opaque)

No 1 < 0.9

appearance Only allowedvalue is metal,which will createa “brushed metal”window

No - < 0.9

autoclosetime Ifautoclosetimeisset to an integernumber larger than1, the dialog willautomatically closeafter the specifiednumber of secondshave passed. Thetimer starts inthe very momentwhen Pashua hasfinished parsing theconfiguration stringand everything is setup.

No - 0.9.1

floating Settingautoclosetimeto1will result in thewindow floatingabove otherwindows.

No 0 0.9.3

x Sets the horizontalposition where thewindow should beopened on the screen( 0is the left borderof the screen)

No Window willbe positionedautomatically

0.9.3

y Sets the verticalposition where thewindow should beopened on the screen

No Window willbe positionedautomatically

0.9.3


6

Name Purpose Required Default Since version( 0is the upperborder of the screen)

Example 2.1. Example window

*.title = A window title*.transparency = 0.95*.x = 50*.y = 60

3. Element type: button

A button works similar to the default button [13]: when clicked, it closes the window and returns allelements’ values, but additionally, the button’s own value is returned as 1. Buttons (“regular” buttons, not thecancel button or the default button) are always positioned in the lower left area of the window, though youcan position them absolutely using attributes x and y

Table 2.2. Attributes for elements of type button

Name Purpose Required Default

label Sets the button’s text Yes –

x Absolute horizontalposition in the window,measured from the leftborder of the content area

No –

y Absolute vertical positionin the window, measured

No –


7

Name Purpose Required Defaultfrom the lower border ofthe content area

disabled If set to value 1, theelement will be disabled,so that the default valuecannot be changed.

No Not disabled

tooltip Text to use as tooltip forthe button

No –

Return value: Either 1 (button clicked) or 0 (button not clicked)

Example 2.2. Example button

b.type = buttonb.label = My button

4. Element type: cancelbutton

A cancelbutton can be triggered using Escape and closes the window without returning any values,except the cancelbutton’s own variable, which will be returned as 1. The cancel button is alwayspositioned to the left of the default button and can not be moved to any other position.

Table 2.3. Attributes for elements of type cancelbutton


label Sets the button title No Automatic title,depending on thelocalization; for instance,in English it’s “Cancel”


No Not disabled

tooltip Text to use as tooltip forthe cancel button

No –

Return value: Either 1 (button clicked / user pressed Escape / user pressed Cmd-W) or 0 (button not clicked)


8

Example 2.3. Example cancelbutton

cb.type = cancelbuttoncb.label = Close this dialogcb.tooltip = Closes this window without returning the values entered

5. Element type: checkbox

Displays a checkbox

Table 2.4. Attributes for elements of type checkbox


label Creates a label / titleabove this element

Yes –

default Set this to 1 if you wantthe checkbox to bechecked by default.

No –


No Not disabled

tooltip Text to use as tooltip forthe checkbox

No –


No –

y Absolute vertical positionin the window, measuredfrom the lower border ofthe content area

No –

relx Horizontal offset, relativeto the position the elementwould have if relx wasnot used (e.g.: relxspecifies the distancefrom the left window

No 0


9

Name Purpose Required Defaultborder). Any integer canbe used as relx value.

rely Relative vertical distanceto the next element below(“relative” means thatthe value is added to thedefault distance). Anyinteger from -20 to 20 canbe used as rely value.

No 0

Return value: Either 1 (checkbox checked) or 0 (checkbox not checked)

Example 2.4. Example checkbox

chk.type = checkboxchk.label = If you like, you can use a really long label, as the window will scale accordinglychk.tooltip = Yes, it’s that simple!

6. Element type: combobox

A combo box is a combination of a popup menu and a textfield: the user can either choose a value from a listor enter any string.

Table 2.5. Attributes for elements of type combobox



No –

option Adds a value to the listof values. Can (usuallyshould) be used more thanonce.

Yes (one option attributeis required, others areoptional)

–

completion Controls if and howautocompletion isperformed. Possible

No 1


10

Name Purpose Required Defaultvalues are 0 (nocompletion), 1 (completesthe first item in thecompletion list whichmatches the enteredstring, case-sensitive),or 2 (ditto, but case-insensitive).


No Not disabled

tooltip Text to use as tooltip forthe combo box

No –

width Width in pixels No 200


No –


No –

relx Horizontal offset, relativeto the position the elementwould have if relx wasnot used (e.g.: relxspecifies the distancefrom the left windowborder). Any integer canbe used as relx value.

No 0


No 0

Return value: String contents (may be an empty string)


11

Example 2.5. Example combobox

cb.type = comboboxcb.label = My combobox labelcb.default = Gromitcb.option = Wallacecb.option = Gromitcb.option = Haroldcb.option = Maudecb.option = Haroldcb.width = 220cb.tooltip = Choose from the list or enter another name

7. Element type: date

The date element lets the user choose a date, a time or both. It can be displayed in a textual or a graphicalstyle.

Table 2.6. Attributes for elements of type date


label Sets the date picker’slabel (displayed above)

No –

textual Should the textual displaystyle be used instead ofthe graphical style?

No 0 (No)

date Should the user be able tochose a date?

No 1 (Yes)

time Should the user be able tochose the time?

No 0 (No)


12


default Default date and/ortime that should beselected when the dialogis opened. The onlystring format that isguaranteed to work is“yyyy-mm-dd [hh:mm]”,for instance “2011-11-2912:34” or “2011-11-29”.Other string formatssuch as “12/24/2004”,“next wednesday” or“tomorrow” may work,too.

No Current date and/or time


No –


No –


No Not disabled


No –

Return value: Depends on the values of attributes date and time. If only a date can be selected, it will bea date string in yyyy-mm-dd format, if only a time can be selected, the format will be hh:mm. If both areenabled, you will get a date and time string in yyyy-mm-dd hh:mm format. If you only need part of thisinformation, you have to extract the desired substrings yourself.


13

Example 2.6. Example date

d.type = dated.label = Example dated.default = 2007-05-30 17:00d.time = 1

8. Element type: defaultbutton

When the default button is pressed, the window is closed and all elements’ values are returned to the callingscript. The default button is always located in the lower right corner of the window and can’t be moved to anyother position.

Note

A default button is added to each window automatically—you only have to specify it explicitly,if you want to set the label or a tooltip or need the return value (i.e.: was it clicked or not?) of thisbutton.

Table 2.7. Attributes for elements of type defaultbutton


label Sets the button title No OK


No Not disabled


No –

Return value: Either 1 (button clicked / user pressed Return) or 0 (button not clicked)


14

Example 2.7. Example defaultbutton

db.type = defaultbuttondb.label = Click here to close the window and save the values

9. Element type: image

This element displays an image (or a PDF file!), optionally scaling it to a maximum width or height. Pashuacan handle any image type that is supported by NSImage. This includes TIFF, GIF, JPEG, PNG, PDF, PICTand EPS

Table 2.8. Attributes for elements of type image



No –

path Creates a label / titleabove this element

Yes –

border Set this to 1 to display aborder for the image

No –

maxwidth If this attribute is set tosome integer number,the image will be scaleddown to this width(including border), if it’swider

No –

maxheight If this attribute is set tosome integer number,the image will be scaleddown to this height(including border), if it’shigher

No –

tooltip Text to use as tooltip forthe image

No –


No –


15



No –


No 0


No 0

Return value: None

Example 2.8. Example image

img.type = imageimg.label = This is Pashua’s icon, scaled down a little bitimg.path = /Applications/Pashua.app/Contents/Resources/AppIcon.icnsimg.maxwidth = 110img.border = 1


16

10. Element type: openbrowser

An openbrowser is used for choosing a filesystem path. It consists of a textfield, a button and(optionally) a label. The textfield holds the actual element value (the file path), while the button (which islocalized [31]) is used to invoke a file selector sheet. Moreover, a file can be dragged & dropped onto thetextfield.

Table 2.9. Attributes for elements of type openbrowser



No –

width Sets the width (overallwidth of texfield andbutton)

No 300

default Default path No –

filetype File types that can beselected in the opendialog or dropped ontothe textfield; takes aspace-delimited list offilename extensions (suchas jpg gif tif etc.).In addition to filenameextensions, you can usedirectory to let theuser choose directories.If only directory isspecified, the user won’tbe able to choose anyfiles. If only filenameextensions are specified,the user won’t be able tochoose directories. If youdon’t specify filetype atall, the user will be ableto choose anything in theopen dialog box.

No –


No –


No –


17



No 0


No 0

Return value: Full filesystem path for the selected item (may be an empty string)

Example 2.9. Example openbrowser

opb.type = openbrowseropb.label = Please select an imageopb.default = image.jpgopb.filetype = jpg tiff tif gif png psdopb.width = 350

11. Element type: password

This element is identical to a textfield [28], except that it hides whatever is typed into it. Moreover,you can’t copy text from a password element.


18

Table 2.10. Attributes for elements of type password



No –

width The textfield’s width inpixels

No 200

default The textfield’s initialcontents

No –


No Not disabled


No –


No –


No –


No 0


No 0



19

Example 2.10. Example password

pw.type = passwordpw.label = Please enter your passwordpw.default = Secret!pw.width = 120

12. Element type: popup

A popup is an element that lets the user choose one value from a list of possible values

Table 2.11. Attributes for elements of type popup


option Any string that shouldappear as an entry in thepopup, can (and probablyshould) be used more thanonce

Yes (one option isrequired, others are (sic!)optional)

–

default Default value (shouldmatch one of theoptionattributes

No –


No –


No Not disabled


No –

width Width in pixels No 200


No –


No –


20



No 0


No 0

Return value: Selected item as string (may be an empty string)

Example 2.11. Example popup

p.type = popupp.label = Example popup menup.tooltip = Quite useless, isn’t it?p.width = 310p.option = Popup menu item #1p.option = Popup menu item #2p.option = Popup menu item #3p.default = Popup menu item #2

13. Element type: radiobutton

A radiobutton element lets the user choose one value from a pre-defined list of values.


21

Table 2.12. Attributes for elements of type radiobutton



No –

option Any string that should beused as a selectable value.Should be used more thanonce.

Yes (at least one optionis required)

–

default The value that should beselected by default. Ofcourse, this must be oneof the option values towork.

No –


No Not disabled


No –


No –


No –


No 0

rely Relative vertical distanceto the next element below(“relative” means thatthe value is added to thedefault distance). Any

No 0


22

Name Purpose Required Defaultinteger from -20 to 20 canbe used as rely value.

Return value: Selected radiobutton’s label as string (may be an empty string)

Example 2.12. Example radiobutton

radio.type = radiobuttonradio.label = How would you like your coffee?radio.option = Blackradio.option = With milkradio.option = With milk and sugarradio.option = Only sugar, no milkradio.default = With milk

14. Element type: savebrowser

A savebrowser can be used for setting a path and name for a new file. It consists of a textfield, a buttonand (optionally) a label. The textfield holds the actual element value (the file path and name), while thebutton (which is localized [31]) is used to invoke a file selector sheet.

Table 2.13. Attributes for elements of type savebrowser



No –

width Sets the width (overallwidth of texfield andbutton)

No 300

default Default path No –

filetype File extension to use forthe save dialog box; if thisattribute is used, the user

No –


23

Name Purpose Required Defaultwill be forced to use thatextension for the name


No –


No –


No 0


No 0

Return value: Full filesystem path (may be an empty string, if no path chosen by user)

Example 2.13. Example savebrowser

svb.type = savebrowsersvb.label = Please set the destination pathsvb.default = /tmp/foosvb.filetype = jpgsvb.width = 360

And this is the sheet you would get after clicking the “Choose…” button:


24

15. Element type: text

This element displays multi-line, wrapping text.

Table 2.14. Attributes for elements of type text



No –

width Sets the width of the text(in pixels)

No 280

tooltip Text to use as tooltip forthe text

No –

default The text to display(synonym for [text]).

Yes (either default ortext must be set)

–


25

Name Purpose Required DefaultYou can use the string“[return]” to insert alinebreak.

text The text to display(synonym for default).You can use the string“[return]” to insert alinebreak.

Yes (either default ortext must be set)

–


No –


No –


No 0


No 0

Return value: None


26

Example 2.14. Example text

txt.type = texttxt.default = Paragraph one, demo text[return][return]Paragraph two

16. Element type: textbox

A textbox is a scrollable, multi-line text container. The scrollbar will appear automatically if needed. Note: Ifyou have changed the system’s scrollbar behaviour to display both arrows at both ends (e.g. using TinkerTool[http://www.bresink.com/osx/TinkerTool.html]), the scrollbar might not appear for small heights.

Table 2.15. Attributes for elements of type textbox



No –

width Sets the width of thetextbox (in pixels)

No 250

height Sets the height of the text(in pixels)

No 52

default Sets the initial contents.You can use the string“[return]” to insert alinebreak.

No –

fontsize Size of the text inside thetextbox. There are threesizes available, whichconform to the system’sstandard sizes: regular,small, or mini .

No regular

fonttype Set this to fixed if thetext should be displayedusing a monospace font.

No –


No Not disabled

http://www.bresink.com/osx/TinkerTool.html

http://www.bresink.com/osx/TinkerTool.html


27


tooltip Text to use as tooltip forthe textbox

No –


No –


No –


No 0


No 0


Example 2.15. Example textbox

tb.type = textboxtb.default = Line 1[return]Line 2[return]Line 3tb.width = 300tb.height = 60


28

17. Element type: textfield

A textfield is a simple, 1-line text input field with an optional label displayed above the textfield.

Table 2.16. Attributes for elements of type textfield



No –

width The textfield’s width inpixels

No 200

default The textfield’s initialcontents

No –


No Not disabled

tooltip Text to use as tooltip forthe textfield

No –


No –


No –


No 0


No 0


29


Example 2.16. Example textfield

txf.type = textfieldtxf.label = Please enter your favourite operating systemtxf.default = Mac OS Xtxf.width = 270txf.tooltip = Quite obvious answer, I think ...

30

Chapter 3. Topics1. Unicode and text encodings

Pashua versions 0.9.1 and above support setting a text encoding for values (but not for element names) in theconfiguration string, with Unicode (UTF-8) being among the supported encodings. For instance, this featurecould be used to pass Japanese or Chinese characters to Pashua or read Russian or Korean characters fromPashua.

While in 0.9.1, the encoding was defined in the dialog configuration itself (which, looking back, was apretty stupid idea—but encodings didn’t work reliably in 0.9.1, anyway …), versions 0.9.2 and above use anoptional command-line argument -e that can be passed to Pashua. Nevertheless, you don’t have to deal withthat argument directly, but merely pass it as 2nd argument to the function that manages the communicationwith Pashua, provided you use one of the examples as a starting point. Practically, this simply means that:

• in Perl, you would have to call Pashua::run($conf, 'utf8') instead ofPashua::run($conf)

• in Python, you would have to call Pashua.run(conf, "utf8") instead of Pashua.run(conf)

• in PHP, you would have to call pashua_run($conf, "utf8") instead of pashua_run($conf)

etc. I guess you’ll see how it works. Of course, you can use any valid encoding string instead of utf8. Thesupported encodings are:

Table 3.1. Table of supported encodings

Encoding argument Description

macroman Classic Macintosh Roman encoding(NSMacOSRomanStringEncoding) – Default

ascii Strict 7-bit ASCII encoding within 8-bit chars; ASCIIvalues 0..127 only (NSASCIIStringEncoding)

nlascii 7-bit verbose ASCII torepresent all Unicode characters(NSNonLossyASCIIStringEncoding)

latin1 8-bit ISO Latin 1 encoding(NSISOLatin1StringEncoding)

utf8 An 8-bit representation of Unicode characters,suitable for transmission or storage by ASCII-basedsystems (NSUTF8StringEncoding)

winlatin1 Microsoft Windows codepage1252; equivalent to WinLatin1(NSWindowsCP1252StringEncoding)

Topics

31

Encoding argument Description

win1253 Microsoft Windows codepage1253, encoding Greek characters(NSWindowsCP1253StringEncoding)

If you need to use, for instance, UTF-8 in your configuration string, it might be necessary to change theencoding of the script itself to match the encoding you want to use with Pashua; many editors supportswitching the encoding (also known as “charset”), so this shouldn’t be much of a problem.

If your editor does not support encodings or for some other reason it’s necessary to leave the script inMacRoman, you should use MacRoman representations of the characters. Simply enter the characters inTextEdit, convert to plaintext, save the document using the desired encoding, close the document and then re-open it in TextEdit, explicitly choosing MacRoman as encoding; you should now see a strange sequence ofcharaters ;-) Copy these characters into your MacRoman script and you’re done.

2. Localization

Pashua is localized in German, French and English. The localizations are used for the menu bar,the application about box, button titles (default button [13], cancel button [7], savebrowser [22] andopenbrowser [16] buttons) and of course for error messages. It’s your application’s responsibility to providelocalization by passing an appropriate configuration string to Pashua for anything else that should belocalized.

3. Dynamic configuration strings

After the release of Pashua 0.7, I got a few mails from users who had problems creating dynamicconfiguration strings or who thought that it’s not possible to create dynamic configuration strings at all.

Of course, configuration strings are (obviously) nothing but strings, and you can use them in any way you canuse a string variable in the programming language you chose. If you like, you can get field values from anOracle database with Perl, fetch them from a Web Service with AppleScript, extract it from some textfile onyour disk, combine them, split them, replace characters in them or anything else you can think of.

To make a long story short: Pashua does not care how the configuration string was created—it only has tofulfill the syntax rules.

The static strings I wrote for the various example files are nothing but the most simple usage example. Forinstance, you could build a configuration string for Perl this way:

my $conf="user.type=textfielduser.label=Field labeluser.width=160";

… or with Heredoc syntax:

my $conf = <<EOCONF;user.type = textfield

Topics

32

user.label = Field labeluser.width = 160EOCONF

… or this way:

my $conf;my %hash = ( 'user', { type=>'textfield', 'label'=>'Field label', 'width'=>160 });

while (my($element, $specs) = each(%hash)) { my %attributes = %$specs; foreach (sort keys %attributes) { $conf .= "${element}.$_ = $attributes{$_}\n"; }}

The result would be exactly the same in any of these cases.

If you take a look at the example scripts, you will see that they make use of dynamic configuration strings:the script’s directory is searched for two hidden image files (.bg.png and .icon.png) and—in case theyexist—they are added to the window configuration.

4. Building “real” applications with Pashua

Native OS X applications are nothing like folders with a name that ends with “.app” (invisible in the Finderby default) and that have a specific directory structure in them. You can examine such a folder (calledan “application bundle”) by context-clicking on the name and choosing the appropriate option from thecontextual menu (in English it is “Show Package Contents”, in German it is “Paketinhalt zeigen”).

As a starting point, an example for a doubleclickable, “real” application with a Pashua GUI is provided.When you play around with the application bundle, there are a few things to keep in mind:

• The script that is the “engine” inside the application bundle must have the same name as the bundle itself(without the “.app” extension).

• The script must have the executable bit set.

• When using a Perl or Python script, you should put the corresponding module inside the same folder(*.app/Contents/MacOS/) as the script.

• I haven’t managed to get AppleScript to work inside application bundles. You can use a wrapper shellscript containing something like

Topics

33

#!/bin/shscriptpath=`dirname "$0"`osascript "$scriptpath/my_applescript.app"

…, but though this will work, the application won’t finish launching (the Dock icon won’t stop hopping).

34

Chapter 4. FAQ1. How do I display 2 or more windows one after another?

You can call Pashua multiple times, but this will result in successive application launches (with the iconmoving in and out of the Dock), which is annoying. Hiding the Dock icon [34] helps a lot in this case, butit’s only a remedy—no real solution.

2. When will Pashua support multiple checkboxes / radiobuttons / …?

I don’t know why, but quite a number of Pashua users seem to think that it’s not possible to use more thanone checkbox in a dialog. Of course, this is not the case. You can use any GUI element as often as you like;the only exceptions are the cancel button [7] and the default button [13]. You only have to make sure that thenames are unique:

chk1.type = checkboxchk1.label = Checkbox 1

chk2.type = checkboxchk2.label = A second checkbox

chk3.type = checkboxchk3.label = Checkbox #3

3. May I distribute applications based on Pashua?

You are allowed to re-distribute Pashua (as an external application or by shipping a modified Pashuaapplication bundle similar to the “Doubleclickable Example”) as long as your application is freeware or OpenSource Software and, additionally, is not merely a free “add-on” to some commercial service you offer.

Of course, I do not give any guarantee that Pashua works as expected and refuse responsibility for anythingthat might be caused by an application which makes use of Pashua.

4. How can I hide the dock icon?

Most Cocoa applications can be modified so that the Dock icon and the application-specific menu bar arehidden—and Pashua is no exception to this rule. You can achieve this by opening the file Info.plistinside Pashua’s application bundle and changing the line below the one containing LSUIElement from<false/>to <true/>. If you don’t notice any change in Pashua’s behaviour, you should log out and backin.

5. Are there any tutorials on using Pashua?

A tutorial was published in O’Reillys “Mac OS X Panther Hacks” as hack #25—and fortunately,you can read it online: www.macdevcenter.com/pub/a/mac/excerpt/pantherhacks/?page=2 [http://www.macdevcenter.com/pub/a/mac/excerpt/pantherhacks/?page=2]

http://www.macdevcenter.com/pub/a/mac/excerpt/pantherhacks/?page=2



FAQ

35

Keep in mind that the text uses the old syntax which worked until version 0.9.1. Hence, all occurrences ofname_attribute in the examples should be changed to name.attribute.

A more recent article was in the December 2007 issue of MacTech magazine.

6. WTF does “Pashua” mean?

I always find it difficult to find names for applications I write, and Pashua was no exeception. As usual, atsome point I started playing around with acronyms from “Perl”, “and”, “shell” (actually, at the beginningI only thought of Perl and shell scripts), “GUI” / “UI” and came up with “Pashua”, which turned out to beambiguous enough to interpret it as “ Perl And SHell Ui- Addon” or “Python And SHell Ui-Addon” or “PhpApplescript Simple, Homemade User interfAce” or whatever ;-)

36

Chapter 5. Version historyFor information on version changes, please take a look at the website [http://www.bluem.net/jump/pashua-versions/].

http://www.bluem.net/jump/pashua-versions/



Documentation

Documents

building real

full filesystem

label title

distribute

file selector

dynamic configuration

textfields

relative vertical