BITMAP(1) AIX BITMAP(1) NAME bitmap, bmtoa, atobm - bitmap editor and converter utilities for the X Window System SYNOPSIS bbbbiiiittttmmmmaaaapppp [ -_o_p_t_i_o_n_s ... ] [ _f_i_l_e_n_a_m_e ] [ _b_a_s_e_n_a_m_e ] bbbbmmmmttttooooaaaa [ ----cccchhhhaaaarrrrssss ... ] [ _f_i_l_e_n_a_m_e ] aaaattttoooobbbbmmmm [ ----cccchhhhaaaarrrrssss _c_c ] [ ----nnnnaaaammmmeeee _v_a_r_i_a_b_l_e ] [ ----xxxxhhhhooootttt _n_u_m_b_e_r ] [ ----yyyyhhhhooootttt _n_u_m_b_e_r ] [ _f_i_l_e_n_a_m_e ] DESCRIPTION The _b_i_t_m_a_p program is a rudimentary tool for creating or editing rectangular images made up of 1's and 0's. Bitmaps are used in X for defining clipping regions, cursor shapes, icon shapes, and tile and stipple patterns. The _b_m_t_o_a and _a_t_o_b_m filters convert _b_i_t_m_a_p files (FILE FOR- MAT) to and from ASCII strings. They are most commonly used to quickly print out bitmaps and to generate versions for including in text. COMMAND LINE OPTIONS _B_i_t_m_a_p supports the standard X Toolkit command line argu- ments (see _X(1)). The following additional arguments are supported as well. ----ssssiiiizzzzeeee _W_I_D_T_H_x_H_E_I_G_H_T Specifies size of the grid in squares. ----sssswwww _d_i_m_e_n_s_i_o_n Specifies the width of squares in pixels. ----sssshhhh _d_i_m_e_n_s_i_o_n Specifies the height of squares in pixels. ----ggggtttt _d_i_m_e_n_s_i_o_n Grid tolerance. If the square dimensions fall below the specified value, grid will be automatically turned off. ----ggggrrrriiiidddd,,,, ++++ggggrrrriiiidddd Turns on or off the grid lines. ----aaaaxxxxeeeessss,,,, ++++aaaaxxxxeeeessss Turns on or off the major axes. ----ddddaaaasssshhhheeeedddd,,,, ++++ddddaaaasssshhhheeeedddd Turns on or off dashing for the frame and grid lines. ----ssssttttiiiipppppppplllleeeedddd,,,, ++++ssssttttiiiipppppppplllleeeedddd Turns on or off stippling of highlighted squares. Rev. Release 5 Page 1 BITMAP(1) AIX BITMAP(1) ----pppprrrrooooppppoooorrrrttttiiiioooonnnnaaaallll,,,, ++++pppprrrrooooppppoooorrrrttttiiiioooonnnnaaaallll Turns proportional mode on or off. If proportional mode is on, square width is equal to square height. If pro- portional mode is off, _b_i_t_m_a_p will use the smaller square dimension, if they were initially different. ----ddddaaaasssshhhheeeessss _f_i_l_e_n_a_m_e Specifies the bitmap to be used as a stipple for dash- ing. ----ssssttttiiiipppppppplllleeee _f_i_l_e_n_a_m_e Specifies the bitmap to be used as a stipple for highlighting. ----hhhhllll _c_o_l_o_r Specifies the color used for highlighting. ----ffffrrrr _c_o_l_o_r Specifies the color used for the frame and grid lines. ffffiiiilllleeeennnnaaaammmmeeee Specifies the bitmap to be initially loaded into the program. If the file does not exist, _b_i_t_m_a_p will assume it is a new file. bbbbaaaasssseeeennnnaaaammmmeeee Specifies the basename to be used in the C code output file. If it is different than the basename in the work- ing file, _b_i_t_m_a_p will change it when saving the file. _B_m_t_o_a accepts the following option: ----cccchhhhaaaarrrrssss _c_c This option specifies the pair of characters to use in the string version of the bitmap. The first character is used for 0 bits and the second character is used for 1 bits. The default is to use dashes (-) for 0's and sharp signs (#) for 1's. _A_t_o_b_m accepts the following options: ----cccchhhhaaaarrrrssss _c_c This option specifies the pair of characters to use when converting string bitmaps into arrays of numbers. The first character represents a 0 bit and the second char- acter represents a 1 bit. The default is to use dashes (-) for 0's and sharp signs (#) for 1's. ----nnnnaaaammmmeeee _v_a_r_i_a_b_l_e This option specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the _f_i_l_e_n_a_m_e command line argument or leave it blank if the standard input is read. Rev. Release 5 Page 2 BITMAP(1) AIX BITMAP(1) ----xxxxhhhhooootttt _n_u_m_b_e_r This option specifies the X coordinate of the hotspot. Only positive values are allowed. By default, no hotspot information is included. ----yyyyhhhhooootttt _n_u_m_b_e_r This option specifies the Y coordinate of the hotspot. Only positive values are allowed. By default, no hotspot information is included. USAGE _B_i_t_m_a_p displays grid in which each square represents a sin- gle bit in the picture being edited. Actual size of the bitmap image, as it would appear normaly and inverted, can be obtained by pressing MMMMeeeettttaaaa----IIII key. You are free to move the image popup out of the way to continue editing. Press- ing the left mouse button in the popup window or MMMMeeeettttaaaa----IIII again will remove the real size bitmap image. If the bitmap is to be used for defining a cursor, one of the squares in the images may be designated as the hot spot. This determines where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the end of the tip; for symmetric cursors (such as crosses or bullseyes), this is usually at the center. Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as symbolic constants giving the width, height, and hot spot (if specified) that may be used in creating cursors, icons, and tiles. EDITING To edit a bitmap image simply click on one of the buttons with drawing commands (PPPPooooiiiinnnntttt,,,, CCCCuuuurrrrvvvveeee,,,, LLLLiiiinnnneeee,,,, RRRReeeeccccttttaaaannnngggglllleeee,,,, etc.) and move the pointer into the bitmap grid window. Press one of the buttons on your mouse and the appropriate action will take place. You can either set, clear or invert the gird squares. Setting a grid square corresponds to setting a bit in the bitmap image to 1. Clearing a grid square corresponds to setting a bit in the bitmap image to 0. Inverting a grid square corresponds to changing a bit in the bitmap image from 0 to 1 or 1 to 0, depending what its pre- vious state was. The default behavior of mouse buttons is as specified below. MouseButton1 Set MouseButton2 Invert MouseButton3 Clear MouseButton4 Clear MouseButton5 Clear This default behavior can be changed by setting the button Rev. Release 5 Page 3 BITMAP(1) AIX BITMAP(1) function resources. An example is provided below. bitmap*button1Function: Set bitmap*button2Function: Clear bitmap*button3Function: Invert etc. The button function applies to all drawing commands, includ- ing copying, moving and pasting, flood filling and setting the hot spot. DRAWING COMMANDS Here is the list of drawing commands accessible through the buttons at the left side of the application's window. Some commands can be aborted by pressing A inside the bitmap win- dow, allowing the user to select different guiding points where applicable. CCCClllleeeeaaaarrrr This command clears all bits in the bitmap image. The grid squares will be set to the background color. Pressing C inside the bitmap window has the same effect. SSSSeeeetttt This command sets all bits in the bitmap image. The grid squares will be set to the foreground color. Pressing S inside the bitmap window has the same effect. IIIInnnnvvvveeeerrrrtttt This command inverts all bits in the bitmap image. The grid squares will be inverted appropriately. Pressing I inside the bitmap window has the same effect. MMMMaaaarrrrkkkk This command is used to mark an area of the grid by dragging out a rectangular shape in the highlighting color. Once the area is marked, it can be operated on by a number of commands (see UUUUpppp,,,, DDDDoooowwwwnnnn,,,, LLLLeeeefffftttt,,,, RRRRiiiigggghhhhtttt,,,, RRRRoooottttaaaatttteeee,,,, FFFFlllliiiipppp,,,, CCCCuuuutttt,,,, etc.) Only one marked area can be present at any time. If you attempt to mark another area, the old mark will vanish. The same effect can be achieved by pressing SSSShhhhiiiifffftttt----MMMMoooouuuusssseeeeBBBBuuuuttttttttoooonnnn1111 and dragging out a rectangle in the grid window. Pressing SSSShhhhiiiifffftttt---- MMMMoooouuuusssseeeeBBBBuuuuttttttttoooonnnn2222 will mark the entire grid area. UUUUnnnnmmmmaaaarrrrkkkk This command will cause the marked area to vanish. The same effect can be achieved by pressing SSSShhhhiiiifffftttt---- MMMMoooouuuusssseeeeBBBBuuuuttttttttoooonnnn3333. CCCCooooppppyyyy This command is used to copy an area of the grid from one location to another. If there is no marked grid area displayed, CCCCooooppppyyyy behaves just like MMMMaaaarrrrkkkk described Rev. Release 5 Page 4 BITMAP(1) AIX BITMAP(1) above. Once there is a marked grid area displayed in the highlighting color, this command has two alternative behaviors. If you click a mouse button inside the marked area, you will be able to drag the rectangle that represents the marked area to the desired location. After you release the mouse button, the area will be copied. If you click outside the marked area, CCCCooooppppyyyy will assume that you wish to mark a different region of the bitmap image, thus it will behave like MMMMaaaarrrrkkkk again. MMMMoooovvvveeee This command is used to move an area of the grid from one location to another. Its behavior resembles the behavior of CCCCooooppppyyyy command, except that the marked area will be moved instead of copied. FFFFlllliiiipppp HHHHoooorrrriiiizzzzoooonnnnttttaaaallllllllyyyy This command will flip the bitmap image with respect to the horizontal axes. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing F inside the bitmap window has the same effect. UUUUpppp This command moves the bitmap image one pixel up. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing UpArrow inside the bitmap window has the same effect. FFFFlllliiiipppp VVVVeeeerrrrttttiiiiccccaaaallllllllyyyy This command will flip the bitmap image with respect to the vertical axes. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing V inside the bitmap window has the same effect. LLLLeeeefffftttt This command moves the bitmap image one pixel to the left. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing Lef- tArrow inside the bitmap window has the same effect. FFFFoooolllldddd This command will fold the bitmap image so that the opposite corners become adjacent. This is useful when creating bitmap images for tiling. Pressing F inside the bitmap window has the same effect. RRRRiiiigggghhhhtttt This command moves the bitmap image one pixel to the right. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing RightArrow inside the bitmap window has the same effect. Rev. Release 5 Page 5 BITMAP(1) AIX BITMAP(1) RRRRoooottttaaaatttteeee LLLLeeeefffftttt This command rotates the bitmap image 90 degrees to the left (counter clockwise.) If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing L inside the bitmap window has the same effect. DDDDoooowwwwnnnn This command moves the bitmap image one pixel down. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing DownArrow inside the bitmap window has the same effect. RRRRoooottttaaaatttteeee RRRRiiiigggghhhhtttt This command rotates the bitmap image 90 degrees to the right (clockwise.) If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing R inside the bitmap window has the same effect. PPPPooooiiiinnnntttt This command will change the grid squares underneath the mouse pointer if a mouse button is being pressed down. If you drag the mouse button continuously, the line may not be continuous, depending on the speed of your system and frequency of mouse motion events. CCCCuuuurrrrvvvveeee This command will change the grid squares underneath the mouse pointer if a mouse button is being pressed down. If you drag the mouse button continuously, it will make sure that the line is continuous. If your system is slow or _b_i_t_m_a_p receives very few mouse motion events, it might behave quite strangely. LLLLiiiinnnneeee This command will change the gird squares in a line between two squares. Once you press a mouse button in the grid window, _b_i_t_m_a_p will highlight the line from the square where the mouse button was initially pressed to the square where the mouse pointer is located. By releasing the mouse button you will cause the change to take effect, and the highlighted line will disappear. RRRReeeeccccttttaaaannnngggglllleeee This command will change the gird squares in a rectangle between two squares. Once you press a mouse button in the grid window, _b_i_t_m_a_p will highlight the rectangle from the square where the mouse button was initially pressed to the square where the mouse pointer is located. By releasing the mouse button you will cause the change to take effect, and the highlighted rectangle will disappear. Rev. Release 5 Page 6 BITMAP(1) AIX BITMAP(1) FFFFiiiilllllllleeeedddd RRRReeeeccccttttaaaannnngggglllleeee This command is identical to RRRReeeeccccttttaaaannnngggglllleeee, except at the end the rectangle will be filled rather than outlined. CCCCiiiirrrrcccclllleeee This command will change the gird squares in a circle between two squares. Once you press a mouse button in the grid window, _b_i_t_m_a_p will highlight the circle from the square where the mouse button was initially pressed to the square where the mouse pointer is located. By releasing the mouse button you will cause the change to take effect, and the highlighted circle will disappear. FFFFiiiilllllllleeeedddd CCCCiiiirrrrcccclllleeee This command is identical to CCCCiiiirrrrcccclllleeee, except at the end the circle will be filled rather than outlined. FFFFlllloooooooodddd FFFFiiiillllllll This command will flood fill the connected area under- neath the mouse pointer when you click on the desired square. Diagonally adjacent squares are not considered to be connected. SSSSeeeetttt HHHHooootttt SSSSppppooootttt This command designates one square in the grid as the hot spot if this bitmap image is to be used for defining a cursor. Pressing a mouse button in the desired square will cause a diamond shape to be displayed. CCCClllleeeeaaaarrrr HHHHooootttt SSSSppppooootttt This command removes any designated hot spot from the bitmap image. UUUUnnnnddddoooo This command will undo the last executed command. It has depth one, that is, pressing UUUUnnnnddddoooo after UUUUnnnnddddoooo will undo itself. FILE MENU The File menu commands can be accessed by pressing the File button and selecting the appropriate menu entry, or by pressing Ctrl key with another key. These commands deal with files and global bitmap parameters, such as size, basename, filename etc. NNNNeeeewwww This command will clear the editing area and prompt for the name of the new file to be edited. It will not load in the new file. LLLLooooaaaadddd This command is used to load a new bitmap file into the bitmap editor. If the current image has not been saved, user will be asked whether to save or ignore the Rev. Release 5 Page 7 BITMAP(1) AIX BITMAP(1) changes. The editor can edit only one file at a time. If you need interactive editing, run a number of editors and use cut and paste mechanism as described below. IIIInnnnsssseeeerrrrtttt This command is used to insert a bitmap file into the image being currently edited. After being prompted for the filename, click inside the grid window and drag the outlined rectangle to the location where you want to insert the new file. SSSSaaaavvvveeee This command will save the bitmap image. It will not prompt for the filename unless it is said to be . If you leave the filename undesignated or -, the output will be piped to stdout. SSSSaaaavvvveeee AAAAssss This command will save the bitmap image after prompting for a new filename. It should be used if you want to change the filename. RRRReeeessssiiiizzzzeeee This command is used to resize the editing area to the new number of pixels. The size should be entered in the WIDTHxHEIGHT format. The information in the image being edited will not be lost unless the new size is smaller that the current image size. The editor was not designed to edit huge files. RRRReeeessssccccaaaalllleeee This command is used to rescale the editing area to the new width and height. The size should be entered in the WIDTHxHEIGHT format. It will not do antialiasing and information will be lost if you rescale to the smaller sizes. Feel free to add you own algorithms for better rescaling. FFFFiiiilllleeeennnnaaaammmmeeee This command is used to change the filename without changing the basename nor saving the file. If you specify - for a filename, the output will be piped to stdout. BBBBaaaasssseeeennnnaaaammmmeeee This command is used to change the basename, if a dif- ferent one from the specified filename is desired. QQQQuuuuiiiitttt This command will terminate the bitmap application. If the file was not saved, user will be prompted and asked whether to save the image or not. This command is pre- ferred over killing the process. Rev. Release 5 Page 8 BITMAP(1) AIX BITMAP(1) EDIT MENU The Edit menu commands can be accessed by pressing the Edit button and selecting the appropriate menu entry, or by pressing Meta key with another key. These commands deal with editing facilities such as grid, axes, zooming, cut and paste, etc. IIIImmmmaaaaggggeeee This command will display the image being edited and its inverse in its actual size in a separate window. The window can be moved away to continue with editing. Pressing the left mouse button in the image window will cause it to disappear from the screen. GGGGrrrriiiidddd This command controls the grid in the editing area. If the grid spacing is below the value specified by grid- Tolerance resource (8 by default), the grid will be automatically turned off. It can be enforced by expli- citly activating this command. DDDDaaaasssshhhheeeedddd This command controls the stipple for drawing the grid lines. The stipple specified by dashes resource can be turned on or off by activating this command. AAAAxxxxeeeessss This command controls the highlighting of the main axes of the image being edited. The actual lines are not part of the image. They are provided to aid user when constructing symmetrical images, or whenever having the main axes highlighted helps your editing. SSSSttttiiiipppppppplllleeeedddd This command controls the stippling of the highlighted areas of the bitmap image. The stipple specified by stipple resource can be turned on or off by activating this command. PPPPrrrrooooppppoooorrrrttttiiiioooonnnnaaaallll This command controls the proportional mode. If the proportional mode is on, width and height of all image squares are forced to be equal, regardless of the pro- portions of the bitmap window. ZZZZoooooooommmm This command controls the zoom mode. If there is a marked area of the image already displayed, bitmap will automatically zoom into it. Otherwise, user will have to highlight an area to be edited in the zoom mode and bitmap will automatically switch into it. One can use all the editing commands and other utilities in the zoom mode. When you zoom out, undo command will undo the Rev. Release 5 Page 9 BITMAP(1) AIX BITMAP(1) whole zoom session. CCCCuuuutttt This commands cuts the contents of the highlighted image area into the internal cut and paste buffer. CCCCooooppppyyyy This command copies the contents of the highlighted image area into the internal cut and paste buffer. PPPPaaaasssstttteeee This command will check if there are any other bitmap applications with a highlighted image area, or if there is something in the internal cut and paste buffer and copy it to the image. To place the copied image, click in the editing window and drag the outlined image to the position where you want to place i, and then release the button. CUT AND PASTE Bitmap supports two cut and paste mechanisms; the internal cut and paste and the global X selection cut and paste. The internal cut and paste is used when executing copy and move drawing commands and also cut and copy commands from the edit menu. The global X selection cut and paste is used whenever there is a highlighted area of a bitmap image displayed anywhere on the screen. To copy a part of image from another bitmap editor simply highlight the desired area by using the Mark command or pressing the shift key and dragging the area with the left mouse button. When the selected area becomes highlighted, any other applications (such as xterm, etc.) that use primary selection will dis- card their selection values and unhighlight the appropriate information. Now, use the Paste command for the Edit menu or control mouse button to copy the selected part of image into another (or the same) bitmap application. If you attempt to do this without a visible highlighted image area, the bitmap will fall back to the internal cut and paste buffer and paste whatever was there stored at the moment. WIDGETS Below is the widget structure of the _b_i_t_m_a_p application. Indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance name. All widgets except the bitmap widget are from the standard Athena widget set. Bitmap bitmap TransientShell image Box box Label normalImage Label invertedImage TransientShell input Dialog dialog Rev. Release 5 Page 10 BITMAP(1) AIX BITMAP(1) Command okay Command cancel TransientShell error Dialog dialog Command abort Command retry TransientShell qsave Dialog dialog Command yes Command no Command cancel Paned parent Form formy MenuButton fileButton SimpleMenu fileMenu SmeBSB new SmeBSB load SmeBSB insert SmeBSB save SmeBSB saveAs SmeBSB resize SmeBSB rescale SmeBSB filename SmeBSB basename SmeLine line SmeBSB quit MenuButton editButton SimpleMenu editMenu SmeBSB image SmeBSB grid SmeBSB dashed SmeBSB axes SmeBSB stippled SmeBSB proportional SmeBSB zoom SmeLine line SmeBSB cut SmeBSB copy SmeBSB paste Label status Pane pane Bitmap bitmap Form form Command clear Command set Command invert Toggle mark Command unmark Toggle copy Toggle move Command flipHoriz Command up Command flipVert Rev. Release 5 Page 11 BITMAP(1) AIX BITMAP(1) Command left Command fold Command right Command rotateLeft Command down Command rotateRight Toggle point Toggle curve Toggle line Toggle rectangle Toggle filledRectangle Toggle circle Toggle filledCircle Toggle floodFill Toggle setHotSpot Command clearHotSpot Command undo COLORS If you would like bitmap to be viewable in color, include the following in the #ifdef COLOR section of the file you read with xrdb: *customization: -color This will cause bitmap to pick up the colors in the app- defaults color customization file: /usr/lib/X11/app- defaults/Bitmap-color. BITMAP WIDGET Bitmap widget is a stand-alone widget for editing raster images. It is not designed to edit large images, although it may be used in that purpose as well. It can be freely incorporated with other applications and used as a standard editing tool. The following are the resources provided by the bitmap widget. Bitmap Widget Header file Bitmap.h Class bitmapWidgetClass Class Name Bitmap Superclass Bitmap All the Simple Widget resources plus ... Name Class Type Default Value foreground Foreground Pixel XtDefaultForeground highlight Highlight Pixel XtDefaultForeground framing Framing Pixel XtDefaultForeground gridTolerance GridTolerance Dimension 8 Rev. Release 5 Page 12 BITMAP(1) AIX BITMAP(1) size Size String 32x32 dashed Dashed Boolean True grid Grid Boolean True stippled Stippled Boolean True proportional Proportional Boolean True axes Axes Boolean False squareWidth SquareWidth Dimension 16 squareHeight SquareHeight Dimension 16 margin Margin Dimension 16 xHot XHot Position NotSet (-1) yHot YHot Position NotSet (-1) button1Function Button1Function DrawingFunction Set button2Function Button2Function DrawingFunction Invert button3Function Button3Function DrawingFunction Clear button4Function Button4Function DrawingFunction Invert button5Function Button5Function DrawingFunction Invert filename Filename String None ("") basename Basename String None ("") Rev. Release 5 Page 13