Main Menu
up
File
New (CRTL+N)
Creates a new image. Beware of the displayed memory usage per layer. When the number turns yellow or red, the program will use a lot of memory and might crash when using too many layers.Open (CRTL+O)
Opens an image from a file.Save (CRTL+S)
Saves the current image. Prompts the user for a filename if image was not saved previously.Save As
Saves the current image. Always prompts the user for a filename.Exit (ALT+F4)
Exits the program.
View
Console
Toggles display of the console.Fullscreen (F11)
Toggles fake fullscreen mode, by resizing the window to take up the entire screen and removing the border.
Presets
Save All
Saves all presets with unsaved changes.
Windows
Manage Charsets
Openes a window that allows the user to select from all available charsets. Information about how to add new charsets is found with the documentation of the charset file format. Note that the default charset is always available.Manage Palettes
Opens a window that allows the user to select from all available colour palettes.
The user is also able to add, rename and save colour palettes. Note that unsaved palettes and palettes with unsaved changes are displayed with a * behind their name.
Add
Adds a new colour palette and selects it. The palette is by default filled with the standart 16 colours supported with the Windows VGA palette and Gray otherwise. Note that this default colour palette is always available when starting the program.Rename
Renames the selected colour palette.Save
Saves the selected colour palette. For more information read the documentation of the colour palette file format.
Export
Image to PNG
Exports the entire image to an png image.Selection to PNG
Exports the selected part of the image to a png image.Layer to TXT
Exports the active layer to an text file.Selection to TXT
Exports the selected part of the active layer to a text file.
Help
About
Shows an about window containing credits and the programs version number. It also has a button to check if a newer version of advASCIIdraw is available and features links to related websites and contact information.Documentation
Opens this webpage.
up
Tools are selected by clicking their icon in the tool bar to the right, or by using the appropriate shortcut. The status bar at the bottom of the screen shows which tool is selected and some tools use it to show additional useful information about their status.
Most tools also have an additional options bar that appears at the top of the screen when the tool is selected. It features additional functions and settings to modify how the tool works.
While most of the tools functions are accessible with the mouse, there are some features that require the use of the keyboard.
Lastly, there are certain features that are always available regardless of the selected tool:
Panning
The user can pan around the image by dragging it with the secondary mouse button.Zooming
The user can zoom in and out of the image by using the mouse wheel.
Using the view tool is synonymous with having no tool selected. The user can pan around the image using either mouse button and zoom in and out.
With the selection tool, the user can select rectangular areas of the image by dragging the primary mouse button. Selected areas can be deleted, filled, moved or copied.
Options
Select All
Selects the entire image.Deselect All
Deselects the entire image.Copy to new Layer
Copies the selected area of the currently active layer into a new and otherwise empty layer that is created above it.
Modifying Selection
Note that the statusbar shows which of the following modes is currently active, whenever the tool is selected.
Selecting
The user can select an area by dragging with the primary mouse button.Moving Selection (ALT)
By holding the ALT key while dragging the user can move the selected area, without modifying the image.Cutting (SHIFT)
When holding the SHIFT key while starting to drag, the selected area is cut from the currently selected layer. Once the mouse button is released the area is merged back into the layer at the new position.Copying (CTRL)
Using the CTRL key serves a function very similar to that of the SHIFT key. But instead of cutting out the selected area, the originally selected area is left intact. The user can drag around the created copy of that area and merge it into the layer at any position by releasing the mouse button.
Shortcuts
Fill (F/INS)
Fills the selected area with the currently active brush.Delete (X/DEL)
Removes all characters from the selected area.Copy (CTRL+C)
Copies the selected area into the clipboard.Cut (CTRL+X)
Cuts the selected area from the active layer and copies it into the clipboard.Paste (CTRL+V)
If the last thing to be copied or cut to the clipboard was a selection from advASCIIdraw, that selection is pasted from the clipboard into the active layer. When pasting, the selected area does not matter, the entire clipboard content is always pasted to the image, provided the image is large enough. However, the top left corners of the selection and of the pasted area will always coincide. Also note, that advACIIdraw uses the system wide clipboard. This means that the user can paste not only within a layer, or an image, but even between images opened after one another, or images opened at the same time in seperate instances of advASCIIdraw.
Be aware that the copying, cutting and pasting shortcuts are fully functional, no matter which tool is active, as long as some area is selected.
The brush tool is the main editing tool of advASCIIdraw. With it the user can draw characters and/or colour by simply holding down the primary mouse button. The tool supports different sizes and shapes and has several other options, modifying how it can be used.
Note that the brush tool can also act as an eraser, when the erasing character is drawn.
Options
Draw Character
Toggles whether or not brush strokes can change the characters of the active layer.Draw Colour
Toggles whether or not brush strokes can change the colour of the active layer.Size
Select the size of the brush.Shape
Select the shape of the brush.Air Brush
Toggles whether or not the brush continues to change the symbols under it while painting, or if each symbol is changed only once per stroke.Fill Rate
Change the fill rate of the brush. Note that the displayed fill rate is only accurate when the air brush is turned off. With the air brush, the brush continues to paint for as long as the primary mouse button is held down, so that even low fill rates can fill most of an area very quickly.
Shortcuts
Pipette (CTRL)
Holding down the CTRL key with the brush tool selected switches to the pipette mode. In this mode the brush does not draw but instead pick up the character and/or colour (depending on the tools settings) directly at the cursor and selects them in the single selection area.
The type tool enables simple text input directly in advASCIIdraw, as well as pasting of text prepared in an outside program.
Note, that before any text can be input or pasted, the user has to set a cursor in the image with the primary mouse button.
Options
Draw Character
Toggles whether or not typing can change the characters of the active layer.Draw Colour
Toggles whether or not typing can change the colour of the active layer.Paste Text
Pastes any text currently in the system wide clipboard at the tools cursor. Note, that this function can only paste text in the extended ASNI format, and that control characters are ignored, with the exception of the new line character which forces a new line. Also be aware that pasting behaves the same way as if the pasted text was typed in manually, including automatic line breaks and cutting off of text if the end of the image is reached.
Inputting Text
Once a cursor is placed, inputting text behaves naturally, except for in specific cases. Both the backspace and return key are functional and the cursor can be moved with the arrow keys. However, if the cursor is moved the tool looses track of the lengths of previous lines and will not be able to jump back to the end of the line correctly. Note also, that the tool automatically jumps to the next line when the right border of the image is reached and will be unable to perform after reaching the bottom of the image.
Shortcuts
Move cursor (←,↑,→,↓)
Moves the cursor one symbol in the given direction.Insert (INS)
Inserts a character from the active brush at the cursor. By holding down the INS key while moving the cursor, each selected tile is filled.Delete (DEL)
Clears the character at the cursor. By holding down the DEL key while moving the cursor, each selected tile is cleared.
Charset Window
up
Note that the charset window functions very similarly to the palette window and their documentation is virtually identical
The charset window lets the user select which character or characters they want to draw. One can either draw a specific character, or use modifyable presets to create customised brushes. Whether single characters or presets are used depends on which tab in the window is active.
Single Tab
Selection Box
By pressing and holding the primary mouse button on the selection box, the user can open a pop up showing the entire charset. A different character can be chosen by dragging and releasing the mouse when the desired character is selected.
Preset Tab
The preset tab allows for the creation and use of customisable brushes. A preset consists of any number of characters, each of them associated with a percentage, all of them adding up to 100%. When the preset is used to draw, characters are selected from it at random, according to these percentages.
Preset Management
The preset tab features a drop down list box, that holds all available presets. A preset can be selected by clicking the box and selecting the desired preset in the appearing list box.
Additionally, presets can be added, renamed, saved and deleted. Note that presets that have unsaved changes are marked with a * after their name. The program does not prompt the user to save unsaved presets on exit.
Add
Adds new empty preset to the bottom of the preset list an d selects it.Rename
Opens a prompt to rename to selected preset. Only alphanumerial characters, spaces, - and _ are allowed.Save
Saves the selected preset. For the saving directtory and file format check the documentation on the preset file format.Del
Deletes the currently selected preset. Also deletes the corresponding preset file.
Preset Manipulation
The selected preset is displayed in a list box, one character per line. For each character there are individual settings:
ASelect Character
Shows the character selected for this preset item. Pressing with the primary mouse button opens a character selection box, identical to the one used on the single selection tab.-Decrease Percentage
Decreases the percentage with which this character is drawn. Increases the percentage for all other characters in the preset.+Increase Percentage
Increases the percentage with which this character is drawn. Decreases the percentage for all other characters in the preset.xRemove Character
Deletes that character from the preset.+++Add New Character
Adds a new character to the preset. The default character is the erasing one, and the default percentage is 0%, unless this is the first character, where it is 100%
Palette Window
up
Note that the palette window functions very similarly to the charset window and their documentation is virtually identical
The palette window lets the user select which colour or colours they want to draw. One can either draw a specific colour, or use modifyable presets to create customised brushes. Whether single colours or presets are used depends on which tab in the window is active.
Single Tab
Selection Box
By pressing and holding the primary mouse button on the selection box, the user can open a pop up showing the entire colour palette. A different colour can be chosen by dragging and releasing the mouse when the desired colour is selected.Set
Opens a colour selection dialog allowing the user to change the selected colour of the preset. Note that these changes are not saved unless the palette is saved in the "Manage Palettes" window, accessible through the main menu.
Preset Tab
The preset tab allows for the creation and use of customisable brushes. A preset consists of any number of colours, each of them associated with a percentage, all of them adding up to 100%. When the preset is used to draw, colours are selected from it at random, according to these percentages.
Preset Management
The preset tab features a drop down list box, that holds all available presets. A preset can be selected by clicking the box and selecting the desired preset in the appearing list box.
Additionally, presets can be added, renamed, saved and deleted. Note that presets that have unsaved changes are marked with a * after their name. The program does not prompt the user to save unsaved presets on exit.
Add
Adds new empty preset to the bottom of the preset list an d selects it.Rename
Opens a prompt to rename to selected preset. Only alphanumerial characters, spaces, - and _ are allowed.Save
Saves the selected preset. For the saving directtory and file format check the documentation on the preset file format.Del
Deletes the currently selected preset. Also deletes the corresponding preset file.
Preset Manipulation
The selected preset is displayed in a list box, one colour entry per line. For each entry there are individual settings:
■Select Colour
Shows the colour selected for this preset item. Pressing with the primary mouse button opens a colour selection box, identical to the one used on the single selection tab.-Decrease Percentage
Decreases the percentage with which this colour is drawn. Increases the percentage for all other colours in the preset.+Increase Percentage
Increases the percentage with which this colour is drawn. Decreases the percentage for all other colours in the preset.xRemove Colour
Deletes that colour from the preset.+++Add New Colour
Adds a new colour to the preset. The default colour is the first one(index 0), and the default percentage is 0%, unless this is the first colour, where it is 100%
Layer Window
up
The layer window holds an overview over all the layers in an image, and lets the user select, create, delete and merge layers, hide or show layers, and change a layer's name and other settings.
Layers can be selected by clicking on them, and reorded by dragging them up or down the list with the primary mouse button. Note, that for the purpose of this documentation, the selected layer and the active layer are synonymous.
Layer Management
New (ALT+N)
Creates a new layer above the currently active layer and selects the new layer. When no image is open clicking this button opens the new image dialog.Delete
Deletes the selected layer from the image. The layer that was below the selected layer becomes the new selected layer.Merge Down
Merges the selected layer with the layer directly beneath it. The selected layer overrides the second one in all characters that are not set to the erasing/transparent character.Overlay Layer
This displays and toggles whether the active layer is an overlay or transparent layer. Overlay layers are not only transparent on characters set to the erasing/transparent character, but also on the background of all other characters. Aside from artistic purposes, practical applications for this feature include a layer used for semi transparent dust, steam, clouds, smoke and similar effects.Background Layer
This displays and toggles whether the active layer is a background layer. All characters in all background layers are always displayed, even if they are occluded by characters in non-overlay or even other background layers. Aside from artistic purposes, this is useful for changing the background colour or texture of parts of the image.
Layer Options
Show Layer
Toggles whether that layer is currently visible. Invisible layers are completely ignored when drawing the image...Rename Layer
Temporarily turns the layer name into a text input box allowing the user to change the layer's name.
Keyboard Shortcuts
up
While shortcuts corresponsing to specific tool or interface options are mentioned above with the corresponding feature, here is a complete list of all keyboard shortcuts and controls in advASCIIdraw:
Interface
Files
CTRL+N
Creates a new image.CTRL+O
Opens an image file.CTRL+S
Saves the current image.
Copy & Paste
CTRL+C
Copies the currently selected area of the active layer into the system wide clipboard.CTRL+X
Cuts(copies and removes) the currently selected area of the active layer into the clipboard.CTRL+V
Pastes the copied or cut area from the clipboard into the active layer, aligning the top-left most characters of the selection and the pasted area.
Other
ALT+N
Creates a new layer.ALT+F4
Exits the application.F11
Toggles borderless window fullscreen mode.
Select Tools
These keys select their respective tool. Note that you cannot select a different tool with these while the typing tool is selected.
V
Select View tool.S
Select Selection tool.B
Select Brush tool.T
Select Typing tool.
Tool Modifiers
These keys change the function of the primary mouse button when using tools.
ALT
Selection Tool: Move selection leaving characters in place.SHIFT
Selection Tool: Move selection and selected characters(cuts).CTRL
Selection Tool: Move selection and selected characters, leaving original characters in place(copies).
Brush Tool: Pipette mode, selecting character and/or colour under cursor for further drawing.
Other Tool Shortcuts
←,↑,→,↓
Type Tool: Move cursor.F/INS
Selection Tool: Fills the selected area with the currently active brush.
Type Tool (INS only): Inserts character from active brush at cursor.X/DEL
Selection Tool: Clears the selected area. Has the same effect as filling with the erasing character.
Type Tool (DEL only): Clears character at cursor.
Console
up
The console of advASCIIdraw has two main functions. First, it confirms certain user actions that do not necessarily have visible effects, like copying into the clipboard. The second function are commands that the user can enter to force certain actions or modify the behaviour of the program in certain ways. Note that when the console displays any status message, entered command or anything else the last line will be shown towards the bottom of the editing area for a few seconds. This is especially useful to confirm that using a shortcut had the desired effect.
The console commands of advASCIIdraw are a feature that most users do not need to worry about. It features mainly commands that are not reachable using the normal user interface and serves purposes of debugging and error reporting. The console can be opened from the View item in the main menu.
A command can be entered into the input field of the console and confirmed by pressing ENTER or with the submit button. Previous commands can be selected, changed and resubmitted by the UP and DOWN arrow keys.
Note that console commands are meant for the experienced user only and have few saveguards to prevent them from causing harm to the running program. The available commands are as follows.
? / help
Lists the available console commands. Add any command as parameter, or type "command?" to display a detailed description for any command.c.clear
Clears the console window.c.tofile.all
Outputs the entire console to a file, and continues writing to it, if no continuous logging is running already.c.tofile.start
Starts logging all future console lines to a file.c.tofile.stop
Stops logging to file.charset.set
Selects the charset with the given name.exit / quit
Exits the application.export.png.all
Exports the entire image to a png file.export.png.maxpixels
Sets or outputs the maximum number of pixels allowed per png export. Set to 0 for no limit. Be aware that exporting very large images can crash the program. The default limit is 16777216pxl or 16Mpxl.export.png.selection
Exports the selected part of the image to a png file.export.txt.eol
Sets or outputs the line ending style with which text files are exported. Allowed values are 'win' and 'unix'.export.txt.layer
Exports the active layer to a text file.export.txt.selection
Exports the selected part of the active layer to a text file.image.new
Creates a new image of given dimensions.io.compressfiles
Toggles whether saved files use compression.palette.color.set
Sets or outputs the hexadecimal value of the colour of specified index of the selected colour palette.palette.set
Selects the palette with the given name.rt.offset
Changes the offset used to draw to render targets. This is used for rendering some listboxes. Changing these values can fix display bugs that happen on some machines. Note that x and y values can be accessed individually by adding ".x" or ".y" to the command.selection.drawtransparency
Toggles whether the erase character in dragged selected areas is drawn as transparent or as red X.ui.expandableselectors.fixed
Toggles whether the character and colour selection pop ups move with relation to the selection or stay fixed while the selection moves.version.check
Connects to amulware.net to check if a newer version of advASCIIdraw is available.
up
Most files used by advASCIIdraw are plain text files and can be edited with any regular text editor. All these plain text files allow for comments marked by the # symbol. Anything in a line after a # is ignored for any of these files. Further, whitespace at the beginning and end of lines as well as empty lines or lines containing only whitespace are also ignored. For all files that represent an entity in the application (like a preset or colour palette) the filename without the extension is also used as a name when displaying that entity.
Unless otherwise specified, all paths below are to be taken with respect to the advASCIIdraw executable.
The advASCIIdraw settings file is located at data/settings.ini. Any line in it will be executed in the applications console upon start of the program. This means that all console commands are valid settings, though not all of them are useful and some of these, like quit may be disallowed in the future.
This file is particularly useful for setting different default settings for the interface or rendering to fix glitches or set user preferred preferences. For changes to the settings file to take effect, the program has to be restarted. The most useful console commands for the settings file are:
Set custom preferences:
- charset.set
- palette.set
- selection.drawtransparency
- ui.expandableselecros.fixed
Never miss an update:
Debugging or glitch prevention:
- c.tofile.all
- io.compressfiles
- rt.offset
Saved character and colour preset files can be found in data/gfx/charpresets/ and data/gfx/colorpresets/ respectively. As both charsets and colour palettes have 256 entries, these files are of the same format, though in which folder they are placed changes their meaning.
Each preset can contain any number of lines, each corresponding to an entry in the preset. Each line contains two values seperated by a comma. The first is an integer between 0 and 255 (inclusive), the index of the character or colour. Note that for standard charsets, the character index is equal to the ASCII/ASNI value of that character. The second value, an integer or floating point number, is the freqency of that entry in the preset. These frequencies do not have to be fractions and do not have to sum up to 1, 100 or any other particular number. The program will automatically adjust the preset so that the total percentage of all items will sum to 100%.
Presets are allowed to contain multiple entries with the same index, however there is no intrinsic reason for this being a useful feature.
Charsets are defined by two files, which should both be placed in data/gfx/charsets/. One of them is an image file that contains the actual symbols in an equally spaced 16x16 grid, counted row first, starting from the top-left corner of the image. Note here that a standard charset should have the appearance of a character coincide with the appropriate ASCII/ANSI character of the same index. However, non-text based charsets are entirely possible.
Note that the allowed image formats are .bmp, .jpg and .png, the last being preferred for its lossless compression and for providing an alpha channel. In fact, if no alpha channel is provided in the image, the lightness will determine the image's transparency, with lighter pixels being more opaque and darker pixels being more transparent. Also note that the image file should be square and have dimensions that are powers of two(128x128, 256x256, ..). Otherwise there might be display errors.
The second file is a plain text file with extension .chr that contains three lines of assignments of the form "attribute = parameter". The three attributes are image, charwidth and charheight. The first takes the filename of the charsets image as parameter, while the other two define the size of a single character in the image, in pixels.
The name used for charsets in the application is the name of the .chr file.
Colour palette files are placed in data/gfx/palettes/ and contain a set of colours used for drawing in ascASCIIdraw.
A palette file can contain up to 256 lines, that each specify one colour of the palette and do so in the order given. Any more than 256 non-empty, non-comment lines will be ignored and if less than 256 colours are specified, the rest will default to Gray (808080). Each line contains its 24bit RGB colour value as a hexadecimal string. For example FFA500 for Orange, or 0000FF for Blue. The three character shorthands, like C40 instead of CC4400, common in web development, are not supported and will be interpreted as 000C40 instead.
The binary .ascii file format used by advASCIIdraw is custom made for the purpose of storing ASCII image information. It is highly flexible with regards to extension in the future and both backwards and forwards compatible.
A detailed description of the format may be added in the future.