Help Jamyda

Jamyda 1.1 - Jamyda manages your DOSBox applications

Created and coded by Thorsten Hoffmann

Published at SourceForge.net (http://sourceforge.net)

Contact: thoto001@users.sourceforge.net

Published under Gnu General Public License. See file gpl.txt.
More information online:

deutsch: http://www.gnu.de/documents/gpl.de.html
english: http://www.gnu.org/licenses/gpl.html

Content

Resources
What is Jamyda?
Quick start
Working with categories
Adjusting the GUI for newer DOSBox versions

Resources

Look&Feel and Layout-Manager by JGoodies (http://www.jgoodies.com)
Icons taken from http://www.freeiconsweb.com

What is Jamyda?

Jamyda manages applications that will be launched via the tool DOSBox.
The behaviour of DOSBox is controlled by a configuration file that defines, for example, screen resolution and size, sound or periphals like joystick, etc.
The main idea of Jamyda is, on the frst hand, to administrate applications and their settings as links on a graphical user interface and to launch them by double-clicking. On the other hand, sets of DOSBox configuration files can be created and reused for every new or exisitng application, created by Jamyda.
This simplyfies creating new application enormously.

Quick start

Start Jamyda and click the Preferences button of Jamyda.
Fill in the absolute path of the DOSBox executable file.
Of course, you should have installed it. ;-)
Now, apply by clicking OK.
Create a new application by clicking the Add button for applications.
Create a new application link.
Fill in all needed settings.
As soon as all necessary information are provided, the OK button will be enabled.
If no DOSBox configuration is available, yet, create one by clicking this button:
Otherwise, choose a suitable configuration from the combo box and click OK. At this time, you're ready to proceed with step 8.
Create a new DOSBox configuration.
Press the Add button.

A dialog opens. Fill in a name for the configuration and then do the settings in the tabs.
If you need help for some of the settings, focus one of the input components (text fields, combo boxes, check boxes, etc.) and then click the Help button of the dialog. A text viewer opens and jumps directly to the section, the focused parameter belongs to. You'll find some comments for each of the parameter.

Close the two dialog, opened recently with OK. Now, you should be faced with the dialog for application settings again. Close it with OK, if all settings are made correctly.

Now, launch your application by a douvle-click.
If errors occurs, check all settings of Jamyda, application link and DOSBox settings. This should do it.

Have fun with Jamyda!

Working with categories

With Jamyda, applications can now categorized to get a better overview of large amounts of applications.
There are system categories All and Favorites, that can not be edited, and user-defined categories, that can be created in any depth.
The application list is refreshed by every selection in category tree, so only applications, associated with this category are displayed at the time.
Categories are also sorted alphabetically.

New categories can be added by clicking the red circled button (see below) in tool bar or via the context menu of the tree. Editing a category is also made context menu or one of the buttons in tool bar.

The association of an application with a category can be made by dragging and dropping an application over a category in tree or via the settings dialog of applications. This dialog can be displayed by context menu or the edit button in tool bar.
If an application should be associated with the Favorites category, drag&drop or setting the check box in settings dialog of the application is a good way for it.

Adjusting the GUI for newer DOSBox versions

Jamyda provides the capability to adjust the GUI by editing a text file in XML-Format for any DOSBox versions. This can be done via a simple text editor.
The following chapter describes the structure of the XML file and prvides some examples.

The XML file is located in sub directory config/ and is named default_072.xml (because the current version of DOSBox was 0.72 at the time of writing this help).

A short review about the general structure of XML:

Every element (tag) encloses a block that can contain sub elements. So, every starting tag has a corresponding end tag. The name of the end tag starts with a /. Example: <element></element>
If a tag contains no sub tags (see tag item), a short form can be used: <element />.
Starting tags can (optional) contain attributes that consist of a parameter name and a value, enclosed by ". Example: <element name="foo"></element>
End tags never contain attributes!
Case sensitivity is very important. Otherwise, tags and attributes can not be interpreted, which occurs errors.

The following table describes the available tags and theirs attributes:

Tag	Attributes	Description
configfile		The root tag. This must occurs exactly one time as the first tag and encloses all other tags. It's, so to say, the border around the configuration and contains only group tags.
	name	The name of the configuration. It will be displayed in the dialog DOSBox configurations.
	dosboxversion	The version of DOSBox, this configuration is specified for. This attribute is just for information at the time and has no further meanings.

group		This tag represents a group and encloses sections. It will be representes by a tab in GUI. A group encloses only sections.
	name	The name of the group and title of the tab in GUI.

section		This tag represents a section and encloses items. It will be representes by a titled border in GUI. A section encloses only items.
	name	The name of the section and title of the border in GUI.

item		Finally, the item is the element, representing a parameter for DOSBox configurations. That's why editing must be done very carefully. Otherwise, strange behaviour of DOSBox can take effect on wrong usage of parameters.
	name	The name of the item. It must be named exactly as the parameter in DOSBox config file! It's case-sensitive. This text will be put into the config file, used by DOSBox on launching the application. Below, some examples are given, how the items are related to DOSBox parameters.
	value	This attribute represents the current value for the parameter (defined by attribute name above). Here, the attribute can be used for setting a default value and should the one, provided by DOSBox (but it's not a must).
	type	The type tags specifies the components in GUI that represent a key-value-pair. For every single parameter, a specific component is usefull. The following types are available: bool Draw a check box. The user can set true or false, only. numberPresents a text field for setting a numeric value. At this time, no validation is implemented to check, whether the typed in text is a valid number or not. text Presents a text field for free text input. multiline_text Provides a text field for entering multi-line texts. It can handle line-wraps. choice Displays a combo box that contains some pre-defined values. Only one of the values can be selected. fileThis typ provides a text filed for entering an absolute path to a file. It also provides a browse button for navigating easily though local directoris/folders. directory The same as type file, but only directories/folders can be selected by browse dialog. But there's no validation, whether the typed in path is a file path or directory path, at this time. So, it's recommended to use the browse dialog.
	values (needed for type choice, only)	This specifies all available values for comboboxes. It's a string with comma-separated (",") values. So, values should never contain a coma itself, because all characters behind this coma would be interpreted as a new value. Note, that XML has some reserved character, like: <, >, " All values to specify can be copied and pasted via the clipboard from the DOSBox configuration file, normally.
	choices (needed for type choice, only)	This is a special option. DOSBox knows a special case to specify two values, separated by a comma, for one parameter. That's why this attribut has been created. The value must be a number > 1 and defines, how many combo boxes will be displayed in GUI. The default value is 1, so this attribut has to be specified only in case of to provide more than one combo box. All combo boxes contain the same values to choose as specified in attribut values. Se examples below.

Examples:

<item name="fullscreen" value="false" type="bool" />
Displays a checkbox that returns true (checked) or false (unchecked). The corresponding entry in the DOSBox configuration file can be: fullscreen=false or fullscreen=true
<item name="fullresolution" value="original" type="choice" values="original, fixed size"/>
Represents a combobox with the choosable values original and fixed size. So, this can be written to DOSBox: fullresolution=original or fullresolution=fixed size. Note that the attribute choices is absent, because only one combo box is needed here.
<item name="priority" value="higher,normal" type="choice" values="lowest,lower,normal,higher,highest,pause" choices="2"/>
This displays two combo boxes, because of the attribute choices="2", but both contains the same set of values to choose. As you can see in attribute value, the first combo box will be selected to the value higher, the second one to normal. And that's the key-value-pair that is written to DOSBox in this case: priority=higher,normal. Both values are separated by a comma.