| SilverEngine
Application Development
A SilverEngine application is one that manipulates, and typically views or renders, SilverScreen drawings using of the SilverEngine DLL. Manipulation of SilverScreen drawings is largely the province of the SilverScreen API, and is not covered here. What is relevant here is the startup and shutdown of the SilverEngine DLL, and aspects relating to viewing and rendering SilverScreen drawings. Loading SilverEngine SilverEngine is implemented as a Win32 DLL. A SilverEngine application should link implicitly to SilverEngine. This means that the bookkeeping tasks associated with locating and loading the DLL, resolving its symbolic references, and unloading SilverEngine are handled by the operating system. It is possible, albeit impractical to link to SilverEngine explicitly, by using the Win32 API function LoadLibrary. Such an approach would require that any needed SilverScreen API functions be obtained via the Win32 API function GetProcAddress. SilverEngine Startup The SilverEngine DLL must be initialized before it may be used. To do this, the engine_initialize function is used. The engine_initialize function supplies SilverEngine with the name of a SilverScreen environment file (.ENV). This environment file contains a number of important startup settings for SilverEngine. Other functions that may be called in the initialization phase are:
SilverEngine Shutdown SilverEngine shutdown is accomplished automatically when the SilverEngine DLL is unloaded. Typically this means when the SilverEngine client exits. Drawings, Screens and Windows The fundamental document in SilverScreen is a drawing (.DRW). A drawing contains geometry, plus various other structures. Drawings are viewed by associating them with a window on a screen. A screen is a viewing area that is composed of tiled windows, and possibly containing overlay windows that overlap the underlying tiled windows. SilverScreen maintains a list of drawings, and a list of screens. Each screen maintains its own list of the windows that comprise the screen, and each window refers to the drawing that is displayed in the window.
Fig. 1 SilverScreen Screen/Window/Drawing Architecture Screens Screens are accessed by name. The name of the currently active screen is obtained by using the function sys_screen. A list of the current screens may be obtained by using the function collect_generic( GN_SCREENS, … ), and their names may then be obtained by using get_generic. Screen dimensions are 0-based from the top-left corner: to obtain the width and height of the currently active screen, use the variables vpixel_right and vpixel_bot. To change to a different screen using its name, use the command SCREEN GOTO <screen-name>. Windows SilverScreen windows are accessed by window number. Numbers are assigned automatically by the system, and may be changed when certain operations occur, particularly those that create or destroy new windows on the screen. Window numbers are 1-based, and the highest window number on the screen is the number of windows on the screen. The currently active window (in the currently active screen) is obtained by using sys_window. The number of windows on the current screen is given by count_windows. To change to a different window using its number, use the command WINDOW GOTO <window-number>. Drawings Drawings are not directly accessible. The name of the current drawing (that is, the drawing loaded in the current window on the current screen) is obtained by using the function sys_drawing. Drawing attributes may be obtained by various means. To access the current drawing’s geometry, you may obtain the root block by using get_block( "\\" ). Programming Windows applications is a topic that is far too large to cover here in any detail. However, we include a little overview that introduces some basic Windows concepts that are important for SilverEngine development. Windows and Device Contexts Under Windows, a window is the basic unit of display area, that is, a rectangular area of a display device (typically a computer screen). A window is the locus of application output and user input, and is identified to the programmer via its handle (HWND). A device context, or DC, is an operating system object that allows the application to draw on a window, and in particular, contains an associated bitmap representing the display surface of the window. A device context is identified to the programmer via its associated handle (HDC). Windows graphics functions do not take an HWND as an argument, but rather an HDC. Because an HDC can represent not only a windows on a display screen, but bitmaps and other output devices such as printers, Windows graphics functions take an HDC as an argument. In a Windows application, display is typically handled in response to a WM_PAINT message sent to a window. In such a handler, the application receives an HDC representing the display area to be painted. Applications, Documents, Views and Frame Windows The Microsoft Foundation Classes is a C++ class library that encapsulates many of the standard Windows objects. In particular, two of these are of interest: the window (HWND) and device context (HDC). The MFC classes CWnd and CDC encapsulate HWND and HDC respectively. The MFC application class CWinApp is also important. Applications An application is just another name for a module (executable program or DLL). In MFC, an application is usually encapsulated by a class derived from the CWinApp class. There can be only one CWinApp-derived class in a module. Documents A document in MFC is a file containing user information. With respect to SilverScreen, a drawing (.DRW) is the primary document type. An MFC document is usually represented by a class derived from CDocument. Views A view in MFC is a window in which a document is displayed. An MFC view is usually represented by a class derived from CView. CView is a class where handlers for many common Windows messages, including WM_PAINT and WM_SIZE typically reside. Frame Windows A frame window in MFC is a window that contains an application’s views, plus other UI elements, such as toolbars and menus. In MFC, a frame window is usually derived from CFrameWnd. MFC supports several different types of applications:
Frame windows are often the focal point of UI messages, and SilverEngine uses the frame window, if supplied, as a parent to its own set of UI elements, such as prompting dialogs and popup menus. Overview The essence of SilverEngine usage is to render SilverScreen screens into Windows windows. In order to do this, the sdc_open function is used to make a connection between SilverScreen and Windows. It is important to remember that the application is responsible for maintaining device display; SilverEngine should be used to generate bitmaps for display refresh. Making the Connection sdc_open has as its parameter a pointer to a SDCInitStruct, which contains as its members a window handle (HWND) and two associated device context handles (HDCs). The first HDC is referred to as the draw context, and represents the actual display surface, usually a window on the screen. The second HDC is referred to as the refresh context, and represents a backing bitmap for the first device context. The intent is that you get SilverScreen to render to your refresh DC, and then you update the display (draw DC) from the refresh DC. By doing so, any type of SilverScreen display, whether wireframe, hidden-line, or other hidden-surface rendering, may be refreshed correctly onto the display DC. Managing the Connection sdc_open returns an handle of type SDC which may be used to refer to the connection you’ve made in subsequent calls to sdc_goto or sdc_close. sdc_goto is particularly useful for ensuring that the proper SDC is active when repainting a particular screen. Typically, before you repaint or render the contents of a screen, you would perform the following sequence:
ss_command( "DRAW RECTANGLE 7,130
18,4,0" );
sdc_goto( SDCHandle );
ss_command( "REFRESH ALL" );
::Invalidate( m_hWnd, FALSE );
A Note on Screens Screen size is a very important concept to keep straight in SilverEngine, as it is used in calculating viewing parameters and also in display refresh. Screen size is currently maintained as a single set of variables in SilverEngine – all screens are assumed to be the same size. Since the developer is in control of the windows that are mapped to SilverEngine screens, it is up to the developer to ensure that SilverEngine remains informed as to the proper screen size. This is done by using the SilverC function screen_resize. screen_resize sets the global screen size maintained by SilverEngine. screen_resize should be called before causing a screen or window to be repainted, especially in cases where the screen’s window may have been resized since the previous repaint, or when switching between different sized windows in your application. Closing the Connection When you are finished using a particular SilverEngine connection, as would be the case when you are closing its associated window or view, then you should close it by using the sdc_close function. For MFC applications, it is a relatively simple task to get up and running with the SilverScreen engine. The following describes a pretty simple-minded application. Essentially there are few things to do to integrate SilverEngine:
Note that it is usually not necessary to explicitly add the SilverEngine export library to your link command. The SILVER.H file contains Visual C++ pragmas that cause the compiler to add the appropriate link commands implicitly. CWinApp Modifications In the implementation file (.CPP) for your CWinApp-derived class, find the InitInstance method. The following code should be placed at the top: EngineInitStruct eis; At the bottom, once the main frame window has been created, place the following code: CFrameWnd *f = (CFrameWnd *) AfxGetMainWnd(); Now find the ExitInstance method. Place the following code before the return statement: ss_command( "clear" ); // Clear all drawings. CView Modifications The CView-derived class is where a lot of the action happens. In its header file, find the Implementation section, and add a bit of code: // Implementation Now go to the implementation (.CPP) file. In the constructor for your CView-derived class, add the following initializations: SDCHandle = 0; These member variables must also be cleaned up on destruction. Therefore, in the CView destructor, add the following code: if ( SDCHandle ) SilverEngine assumes that device contexts used to render into are persistent, i.e. private to the application window class. In order to ensure this, you would usually create the window using the CS_OWNDC class flag. So you should now create a PreCreateWindow method for the CView class, and place the following code before the return statement: cs.lpszClass = AfxRegisterWndClass( Most likely the best place to manage application/SilverEngine connections is in the CView::OnSize method. This is where we discover the initial size of the SilverEngine window, and the place we need to handle resizing of the refresh bitmap. So create one, and add the following code: // In first call to OnSize, dimensions are 0,0 Applications for straight Win32 may also use the SilverEngine. The methodology is similar to that used by MFC programs. The task is to tie a Windows window to a SilverScreen screen. In the example that we provide, we create our window, and use sdc_open to make the connection. We also use the same window be our "frame" window, using engine_set_frame_window. Assume that we have the following global variables, used for a single-window application: static HDC MemDC = NULL; In the section where we create the window, we can perform SilverEngine initialization: hwndMain = CreateWindow( Again, a good place to handle SilverScreen Display Context creation is in the handler for WM_SIZE. This fragment would be for the first time that the window was sized, meaning that it’s when the SDC is created. If the SDC has already been created, then we would want to resize the bitmap associated with the refresh DC: if ( ! SDCHandle ) Finally, the WM_PAINT handler refreshes the screen display from the refresh DC: RECT wRect; |
