Graphics Library Updates

Modifications made Monday 24th June 2002

• If KEY_TYPED events are captured, all catchable keypresses are now reported to the program. Keys such as "DELETE", "LEFT-ARROW", and "PAGE-UP" have been assigned codes just outside the normal ASCII range, but still wihtin the bounds of a char variable. The following defined constants give the codes for these keys:
  • KEY_ESC
  • KEY_BACKSPACE
  • KEY_TAB
  • KEY_F1
  • KEY_F2
  • KEY_F3
  • KEY_F4
  • KEY_F5
  • KEY_F6
  • KEY_F7
  • KEY_F8
  • KEY_F9
  • KEY_F10
  • KEY_F11
  • KEY_F12
  • KEY_INSERT
  • KEY_DELETE
  • KEY_HOME
  • KEY_END
  • KEY_PAGE_UP
  • KEY_PAGE_DOWN
  • KEY_UP_ARROW
  • KEY_DOWN_ARROW
  • KEY_LEFT_ARROW
  • KEY_RIGHT_ARROW
  • KEY_ENTER
  • KEY_MENU
  • KEY_PAD_5
  Note that all keys on the numeric keypad are just repeats of other keys, except the "5" when "num-lock" is off.
• string GetCharacterName(int c) converts any character code into a fully human-readable string describing it exactly.
• SetCaption(string s) Sets the text in the title bar of the window.
• RestrictDrawingTo(Region r); [A Region is a rectangular sub-area of the screen; functions for making Regions are described below] All drawing operations are clipped to the specified region: any drawing outside this region has no visible effect, but all operations behave as normal otherwise.
• UnrestrictedDrawing(); Cancels the effect of RestrictDrawingTo.
• Region MakeRegionXYXY(int x1, int y1, int x2, int y2) creates a Region object suitable for passing to RestrictDrawingTo; the region is rectangular with (x1,y1) as the top-left corner, and (x2,y2) as the bottom-right corner.
• Region MakeRegionXYWH(int x, int y, int w, int h) creates a Region object suitable for passing to RestrictDrawingTo; the region is rectangular with (x,y) as the top-left corner, and (x+w,y+h) as the bottom-right corner.

Modifications made Thursday 13th June 2002

• Exit(); Like the stdlib function exit(1) but compatible with graphics. Stops the program permanently, but does not destroy any open windows.
• CaptureEvents(e); Used to notify the system which kinds of events you want your program to be given. Programs are only notified of events that are explicitly requested with CaptureEvents. These are the following kinds of events:
  • MOUSE_PRESS_L The left mouse button being pressed
  • MOUSE_PRESS_M The middle mouse button being pressed
  • MOUSE_PRESS_R the right mouse button being pressed
  • MOUSE_RELEASE_L The left mouse button being released
  • MOUSE_RELEASE_M The middle mouse button being released
  • MOUSE_RELEASE_R The right mouse button being released
  • MOUSE_CLICK_L The left mouse button being clicked
  • MOUSE_CLICK_M The middle mouse button being clicked
  • MOUSE_CLICK_R The right mouse button being clicked
  • MOUSE_CLICKS Any mouse button being clicked
  • KEY_TYPED A chanracter (except control-C) being typed on the keyboard
  • CONTROL_C_TYPED Control-C being typed on the keyboard
  • WINDOW_RESIZED The window changing size dut to user action.
  • WINDOW_MINIMIZED The window being minimised (reduced to an icon on the task bar)
  • WINDOW_RESTORED The window being restored from minimized state
  • WINDOW_CLOSED The window being closed
  • WINDOW_EVENTS Any of the window events except WINDOW_CLOSED
  • TIMER_SIGNAL A timer "going off"
  • MENU_SELECTED A Menu item being selected by the user.
  Notes about events
  • Programs receive notification of these events happening by using the GetNextEvent function described below.
  • The effect of CaptureEvents() can be reversed by using the IgnoreEvents() function described later.
  • A group of events may be requested either by using multiple calls to CaptureEvents or by using the | operator to combine multiple event names in one call: This
            CaptureEvents(BUTTON_PRESS_L);
            CaptureEvents(BUTTON_PRESS_R);
    is equivalent to this:
            CaptureEvents(BUTTON_PRESS_L | BUTTON_PRESS_R);
  • As events occur they are put into a queue, so that they can be received later. There is room for 1000 unreceived events to be waiting in the queue. Events will always be received in the correct order, even if there is a long delay between the event happening and the program getting around to seeing it.
  • A mouse click is a mouse press followed by a mouse release at almost exactly the same position. If all three of BUTTON_PRESS_L, BUTTON_RELEASE_L, and BUTTON_CLICK_L are selected, then a proper click with the left mouse button will generate all three events in turn.
  • MOUSE_CLICKS is equivalent to MOUSE_CLICK_L | MOUSE_CLICK_M | MOUSE_CLICK_R.
  • If you capture KEY_TYPED events, then keyboard input will no longer be received in the normal way: read_char() etc will not work. Instead, any key except control-c will generate a KEY_TYPED event message containing the ascii code of the key pressed..
  • If CONTROL_C_TYPED events are captured, then control-c will no longer stop the running program, it will be treated as a perfectly normal character producing a KEY_TYPED event. Its ascii code is 3.
  • When the window is resized (by the user dragging an edge or corner, or pressing the maximise button), it is not necessary for the program to do anything; the graphics system automatically notes the new window size. However, if you want to redraw the window contents to fit the new size, WINDOW_RESIZED is the event to capture.
  • There is no need to take any notice of WINDOW_MINIMIZED events. Except that if a program does a lot of work continually drawing things, it can save the effort when the window is minimised and therefore invisible. The WINDOW_RESTORED only (and always) happens when a previously minimised window becomes visible again. Maximising a window is nothing special, it simply produces a produces a WINDOW_RESIZED event.
  • When the close button (with a X in it, top right of any normal window) is pressed, the normal effect is to close the window, and if that is the last window to close, the program is stopped. If WINDOW_CLOSED events are captured, this no longer happens, the only effect of clicking the close button is to generate a WINDOW_CLOSED event. The program may choose to close the window itself using the CloseWindow() function.
  • Programs may request automatic timers that expire, or "go off" at some pre-set time in the future, using the StartRegularTimer or StartSingleTimer functions described below. When a timer goes off, it generates a TIMER_SIGNAL event.
  • It is no possible to add normal menus to the graphics window. When a menu is selected and clicked by the user, it generates a MENU_SELECTED event.
• IgnoreEvents(e) takes exactly the same parameters as CaptureEvents(), but it cancels the request to receive a particular kind or group of kinds of events.
• GetEventName(e) takes exactly the same parameters as CaptureEvents(), returns a string giving the name of the indicated event.
• int GetNextEvent(e, x, y, t, c) the five parameters must be int variables. The next event from the queue is removed, and its details are put into the five variables e, x, y, t, and c, and the result of the function is 1. The value of e is one of the event names listed above; the values of x and y depend on what kind of event has occured, and are described below. The value of c is the Cause of the event: 0 means it was caused by the user, 1 means it was caused by the program. The value of t is always a 'timestamp' for when the event occured: the number of milliseconds since the program started. (If the program has been running without interruption for 25 days, the timestamp will become too big for an integer variable, and won't be totally reliable). If there were no events in the queue, e is set to the constant NOTHING_HAPPENED, and the returned value is 0.
  • All Mouse Events: the values of x and y are the pixel coordinates of where (within the window) the event occured.
  • WINDOW_RESIZED events: x is the new width of the window, and h the new height. c is 1 if this was caused by a call to the SetSize function, or 0 if caused by user action.
  • KEY_TYPED events: x is the ascii code of the key typed.
  • There is no such thing as a CONTROL_C_TYPED event. CONTROL_C_TYPED is how you ask to be notified of control-c being typed, but the corresponding event is a KEY_TYPED event with x set to 3, the ascii code for control-c.
  • TIMER_SIGNAL events: x is set to the identification number of the timer that went off. c will always be 1.
  • MENU_SELECTED events: x is set to the identification number of the menu item that was selcted.
  • All others: x and y have no meaningful value.
• WaitAndGetNextEvent(e, x, y, t) is exactly the same as GetNextEvent except that whereas GetNextEvent always returns immediately even if no events have occured yet, WaitAndGetNextEvent will never return until a real event has happened.
• LimitedWaitAndGetNextEvent(timeout, e, x, y, t) The same as WaitAndGetNextEvent, except that there is a limit to how long it will wait for an event. the 'timeout' parameter is a floating point number, and specifies the maximum time (in seconds) that it will wait. If that time expires, it behaves like GetNextEvent, returning 0 and setting e to NOTHING_HAPPENED.
• SendEvent(e, x, y); or
• SendEvent(e, x, y, c); Artificially generates the event of kind e, with parameters x and y, and sets the cause to c (if c is not supplied, it is set to 1, the signal for an artificial event). All parameters must be ints. If events of type e have not been enabled for capturing, this has no effect.
• int StartSingleTimer(t) starts a timer, which will wait t seconds (t is floating point), then cause a TIMER_SIGNAL event, and never do anything again. Rememeber to enable capturing of TIMER_SIGNAL events. The result returned by StartSingleTimer is the identification number for the timer just created. It is possible to have many timers all ticking at the same time. When any timer goes off, the event it causes contains its own identification number so that the program can tell which timer it was if necessary. Timer events always ahve a cause equal to 1 because they are caused by the program, not by the user.
• int StartRegularTimer(t) exactly the same as StartSingleTimer, except this is a repeating timer: it generates an event every t seconds instead of just once.
• SetSize(w, h); Changes the size of the window, as though the user had dragged the bottom right corner with the mouse. This function generates a WINDOW_RESIZED event with the Cause set to 1.
• CloseWindow(); Closes the graphics window, as normally done by clicking the close button.
• AddMenuBar(); Adds an empty menu bar to the graphics window. This function is not necessary, as AddMenu() will automatically create the menu bar if it doesn't already exist.
• AddMenu(string name); Adds a pull-down menu to the menu bar. There are initially no selectable items in this menu. This function is also not needed because the AddMenuItem function automatically creates the necessary menu if it isn't already there.
• int AddMenuItem(string menuname, string itemname); For example, if you want to add an "Exit" item to the "File" menu, which is the normal setup for windows programs, use m=AddMenuItem("File","Exit"); The value returned is the identification number for this menu item. When the user clicks on this menu item, a MENU_SELECTED event is sent, containing this identification number. Rememeber to enable capturing of MENU_SELECTED events.
• StartBatching(); Before each drawing operation, the graphics system has to gain control of the screen, and then release control immediately afterwards. This is Always Automatic, you do not need to use StartBathcing() ever. However, if you are performing a reasonably large number of tiny operations all at once (perhaps drawing a whole row of an image one pixel at a time) the time taken to gain control before each single operation can slow things down noticably. Under these circumstances, and no others, StartBatching() gains control of the whole screen and keeps it. Any normal drawing operations subsequently performed don't have to bother. After performing a reasonable number of operations, StopBatching() must be used to release control. Until control is released, none of the automatic refresh operations that are absolutely necessary for maintaining the correct appearance of the screen will be performed. Control must not be kept for a long perios, not even a large fraction of a second.
• StopBatching(); Reverses the effect of StartBatching().
• int IsBatching() returns 1 is batching is on (StartBatching has been called, but StopBatching hasn't yet), or 0 otherwise.

Modifications made Thursday 13th June 2002

Modifications made Thursday 6th June 2002

• SetKeyboardMode(m);, where m may be either NORMAL_MODE or DIRECT_MODE, modifies how keypresses are processed. Under NORMAL_MODE (the default when a program first starts), the backspace key is used to "un-type" a character, and is never received by a running program as the result of read_char(); Control-C terminates the program, and is similarly never received. Under DIRECT_MODE, all keypresses, no matter what they normally represent, become input to the running program; backspace and control-C (amongst others) have no special effect. While in DIRECT_MODE the one-line input buffer at the bottom of the console window disappears, to emphasize the fact that no input buffer processing happens. "Exit", under the File menu in the console window, may still be used to stop a program.

Modifications made Tuesday 4th June 2002

• void read_char_no_echo(char c);
• char read_char_no_echo(void);
• char read_char_no_wait_no_echo(void);

Additions made Thursday 30th May 2002

• int CheckSameVersions() Checks that the .h and .cpp files have the same version number. Returns 1 if same. Prints message and returns 0 if different.
• WaitForMouseEventOrKeyPress(int x, int y, int b); Almost the same as WaitForMouseOrKeyPress, except that it does not wait for a complete click (mouse press followed by mouse release) either event, press or release, is enough to satisfy this function. Hence only one set of variables (x,y) wich receive the coordinates of the mouse press/release. The third parameter again indicates which mouse button was used, but is positive for a press, and negative for a release.
• void GetMouseEvent(int x, int y, int b); A combination of WaitForMouseEventOrKeyPress and GetMouseAction. It delivers the last mouse even (press or release) if there is one, but does not wait if there is not. Also does not wait for a complete click: delivers presses and releases of the mouse separately. b negative for release.

Additions made Saturday 25th May 2002

• Support for .BMP files

• These functions should be able to read any .BMP (windows bitmap) files, but it is possible that some new formats exist. Please report any failures. No other graphics file types (e.g. GIF, JPG) are supported yet, but most drawing programs (e.h. Photoshop) make it easy to convert.
• ImageFromFile(filename) filename must be a string. Reads a graphical image from a file, returns an object of type Image *, or NULL on failure. An Image * object may be drawn in the grapics window using the DrawImage functions.
• DrawImage(Image *img, x, y) or DrawImage(Image *img) Draws an image (as read by ImageFromFile) in the graphics window at position x,y. If x and y are not given, the current pen position is used. Pen position, colour, and direction are left unchanged.
• Example, draws a picture from a file 3 times:

          Image *im=ImageFromFile("c:\\programs\\example36\\porkpie.bmp");
          if (im==NULL)
          { print("Error reading graphics file: ");
            print(GetReasonForFailure());
            newline();
            return; }
          DrawImage(im, 100, 100);
          DrawImage(im, 200, 100);
          DrawImage(im, 300, 100);

• string GetReasonForFailure() If ImageFromFile fails for any reason, it returns NULL as its result, and this function returns a string explaining what caused the failure.
• im->GetSize(w,h); w and h must be int variables. After successfully reading an Image *im from a file, this function determines its size in pixels.
• SaveAsBMP(string filename) The entire contents of the graphics window is saved as a "true-colour" .BMP file with the given name. Warning: BMP files can be big. Width w and Height h pixels produces a file just over 3*w*h bytes.
• SaveAsBMP(string filename, int x, int y, int w, int h) Same as the one-argument SaveAsBMP, except only the portion of the screen starting at co-ordinates (x,y) and with given width an height are saved.
  
  

• Reading pixels after drawing them

• int GetPixelColor(int x, int y) returns the colour of the pixel at co-ordinates x,y encoded as a single integer using the same encoding scheme as the EncodeColor functions.
• GetPixelColor0255(int x, int y, int r, int g, int b) reads the colour of pixel at co-ordinates x,y and stores the red/green/blue values (in the range 0-255) in the parameters r, g, b which must be int variables.
• GetPixelColor(int x, int y, r, g, b) The same as GetPixelColor0255, except the r, g, and b may be float or double variables, and receive values in the range 0 to 1.
  
  

• Font Enumeration

• int GetNumberOfFonts() returns the number of different fonts currently available for use.
• string GetFontName(int i) returns the name of one of the available fonts; i must be positive, and less than the number of fonts. The string returned is suitable for use in the SetFontFace function.
• UseDefaultFont() Reverts to using the default windows font.
  
  

• Dialogues (temporary pop-up windows)

• InformationDialog(string message, string title); Makes a small message box appear on the screen. The program does not continue until the user presses OK. message is the message that appears inside the box. If the message should occupy more than one line of text, the special character \n may be used. Title is optional; if supplied, it appears in the title/drag bar of the dialog window.
• ErrorDialog(string message, string title); The same as InformationDialog except that the dialogue window is less friendly-looking, and more visually suggestive of trouble.
• TerminalErrorDialog(string message, string title); The same as ErrorDialog except that once the user clicks OK after seeing the error message, the program is terminated. TerminalErrorDialog is a way to completely stop a program after giving the user an unmissable message.
• int YesNoDialog(string message, string title); The same as InformationDialog except that the window is suggestive of a question being asked, and has two buttons, one marked YES and one marked NO. The result returned is 1 is the user clicks YES, or 0 for NO.
• string SaveAsFileDialog(suggestedname, directory, extension, title) Starts up the standard dialog for selecting a file that is to be created/written. All parameters are optional. The result returned is the empty string "" if the user selects CANCEL, otherwise the full name (including path) of the selected file. suggestedname is the name that will be used (no path should be provided) if the user just clicks OK without actively choosing a filename. directory is the folder that the dialog starts in, but the user can navigate out of it; if not provided, or "", the current working directory is used. extension is the extension (e.g. "TXT", "DAT") that will be added to the end of the name the user type if the user does not add an extension. title appears in the title/drag bar of the dialog window.
• string OpenFileDialog(suggestedname, directory, title) is the same as SaveAsFileDialog except that it is intended to be used for selecting a file that already exists.
• string GetWorkingDirectory() returns the full path and name of the current working directory.
  
  

• Threads

• A Thread is a separate stream of execution within a program. It is actually a perfectly normal function, except that (once started) the thread and the main program both run at the same time (unlike non-thread function, which stops the main program from running until it is finished). There may be a large number of threads all running at the same time. Threads are useful for background or monitoring tasks, such as listening for mouse activity while the main program continues with its normal tasks.
• Thread name(function); creates (but does not start the execution of) a new thread. The thread is represented by a new C++ variable called name, and the function provided as a parameter is what the thread will do once it is started. The function should return no result (void) and take either no parameters or a single int parameter.
• name.Start(); If "name" is the variable representing a thread, as described above, this starts execution of that thread. This form should be used when the thread function takes no parameters.
• name.Start(int x); If "name" is the variable representing a thread, as described above, this starts execution of that thread. This form should be used when the thread function takes one int parameter; the value of x is passed to the thread function when it is started.
• Example of threads being used:

          void background(int init)
          { for (int val=init; val<init+10; val+=1)
            { Delay(random_in_range(0.1, 2.0));
              printf("%d ", val); }
            printf("done "); }
  
          void main(void)
          { Thread one(background);
            Thread two(background);
            printf("go! ");
            one.Start(10);
            two.Start(20);
            Delay(10.0);
            printf("end "); }

• Explanation of example: Note that a normal call to the function background(100) would print out the number 100, 101, 102, 103, ..., 109 then "done", but with a randomly selected delay of between 0.1 and 2 seconds before each number is printed. If background(10) and background(20) were both running at the same time, we would see the numbers 10, 11, 12, ..., 19, "done" and the numbers 20, 21, 22, ..., 29, "done" all printed out, but randomly interleaved. That is exactly what this program prints, plus the word "go!" before any numbers appear, and the word "end" appears after 10 seconds of printing. This is what the program produced when I just ran it: "go! 2010 21 22 11 23 12 24 13 25 14 15 26 27 28 16 29 done 17 end 18 19 done", but the output could be different for each run.
  
  

• Semaphores

• A Semaphore is a special flag variable that threads may safely use to control access to shared variables. Without semaphores, things can go wrong in surprising ways: if the statements { int temp=x; temp=temp+x; temp=temp-1; x=temp; } is executed once, it should have the effect of setting x to 2x-1. If it is executed twice it should therefore have the effect of x=2(2x-1)-1, or x=4x-3. However, if it is executed at approximately the same time by two different threads (assuming x is a variable they both have access to, it could result in x=4x-3, x=3x-2, x=2x-1, and probably some other values. Access to shared variables should always be protected by a semaphore thus: (if "sem" is an already created semaphore), this exampe would become:

          { sem.WaitUntilClearThenSet();
            int temp=x;
            temp=temp+x;
            temp=temp-1;
            x=temp;
            sem.Clear(); }

  A Semaphore may be either clear or set. "clear" means "OK to proceed"; "set" means "danger: wait". Before using a shared variable, a thread must wait until the semaphore is clear, then set that semaphore so that no other thread may proceed. After using the shared variable, that thread must clear the semaphore otherwise no other thread will be able to continue.
• Semaphore name(); is the way to create a new semaphore, and the variable called "name" which represents it. For the above example, it would be "Semaphore sem();". A semaphore is alwars created in the "clear" state.
• sem.WaitUntilClearThenSet(); makes the current thread wait until the semaphore named "sem" becomes clear (unless it was already clear); then that semaphore is automatically set before proceeding.
• sem.Clear(); Clears the semaphore named "sem". If forgotten, causes deadlock. Must only be used by the thread that previously "set" that semaphore.
• sem.Wait(); exactly the same as WaitUntilClearThenSet but a less expressive name.
• sem.Set(); Sets the sempahore named "sem". Not normally used.
• int sem.IsSet() checks whether the semaphore is set or not. returns 1 if set, 0 if clear. This function tells a thread that it would be made to wait if it called the WaitUntilClearThenSet() function. It is for information only, and MUST NOT be used instead of WaitUntilClearThenSet.
• int sem.IsClear() the opposite of sem.IsClear().

Additions made Tuesday 21st May 2002

• void DrawLineBy(dx, dy); Relative line drawing: if the pen is currently at position (x,y), this function draws a line from (x,y) to (x+dx,y+dy). The new pen position becomes (x+dx,y+dy) and the current direction is set to the direction the line was drawn in.
• void MoveBy(dx, dy); Relative pen movement: if the pen is currently at position (x,y), this function moves the pen to (x+dx,y+dy) without drawing a line. The new pen position becomes (x+dx,y+dy) and the current direction is set to the direction the movement was drawn in.
• void DrawRectangleXYXY(x1,y1,x2,y2); Outline Rectangle: draws the outline of a rectangle. Equivalent to drawing lines between (x1,y1) and (x2,y1), (x2,y1) and (x2,y2), (x2,y2) and (x1,y2), and (x1,y2) and (x1,y1). Does not change the pen position or direction.
• void DrawRectangleXYWH(x1,y1,w,h); Outline Rectangle: draws the outline of a rectangle. Equivalent to drawing lines between (x1,y1) and (x1+w-1,y1), (x1+w-1,y1) and (x1+w-1,y1+h-1), (x1+w-1,y1+h-1) and (x1,y1+h-1), and (x1,y1+h-1) and (x1,y1). Does not change the pen position or direction.
• void FillRectangleXYXY(x1,y1,x2,y2); Solid Rectangle: Eaxactly the same as DrawRectangleXYXY, except that the interior of the rectangle is filled with the current pen colour. Does not change the pen position or direction.
• void FillRectangleXYWH(x1,y1,w,h); Solid Rectangle: Eaxactly the same as DrawRectangleXYWH, except that the interior of the rectangle is filled with the current pen colour. Does not change the pen position or direction.
• SetFontSize(int sz); Sets the font for all subsequent calls to WriteText(). The "point size" of the font is changed to sz; all other attributes remain unchanged. If the required size is not available, the system finds the closest matching font.
• SetFontAttributes(int at); Sets the font for all subsequent calls to WriteText(). The parameter is constructed by adding together any of the following predefined constants: FONT_NORMAL, FONT_BOLD, FONT_ITALIC, FONT_UNDERLINE, FONT_STRIKEOUT. The point size and font name remain unchanged. If the required attributes are not available for the selcted font, the system finds the closest match.
• SetFontFace(int f) Sets the font style to one of the predefined standard fonts. That parameter may be one of FONT_ROMAN, FONT_FIXED, or FONT_SANS_SERIF. (FONT_ROMAN may also be called FONT_SERIF; FONT_SANS_SERIF may also be called FONT_SANS). Point size and attributes of the font are not modified.
• SetFontFace(string fontname) Selects the font with the given name. The name may specify any installed font; if the font is not available, the system will pick a different one. Example names: "Times New Roman", "Comic Sans MS", "Symbol". Point size and attributes of the font are not modified.
• SetFontFace(char *fontname) Same as SetFontFace(string).
• SetFontFaceAttributesSize(string fontname, int fa, int sz) Same as the sequence of calls SetFontFace(fontname); SetFontAttributes(fa); SetFontSize(sz); but more efficient.
• SetFontFaceAttributesSize(char *fontname, int fa, int sz) Same as the sequence of calls SetFontFace(fontname); SetFontAttributes(fa); SetFontSize(sz); but more efficient.
• MeasureText(String s, int w, int h) (the second and third parameters must be variables). This function calculated the space required to write the given text in the current font; the parameters w and h are set to the width and height of that space. Thus, the following sequence of calls: MoveTo(x,y); WriteText("Hello"); MeasureText("Hello", w, h); DrawRectangleXYWH(x,y,w,h); draws the string "Hello" with a box around it.
• MeasureText(char *s, int w, int h) same as above.