Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c100 / 1.ddi / SNAV0111.ZIP / SNAV.PRN < prev next >

Wrap

Text File | 1990-04-16 | 50.3 KB | 787 lines

< the╔══╗╔══╗╔ ╔ ║ ╙╢ ╙╢ ║ █ ║ ║ ║ ╔═══╗ ╠═ ╔═══╗╔ ╔═══╗║ ╔ ╔═══╗╔ ╔═══╗╔ ╓─╖ ╔═══╗╔ ╔═╗╔═╗╔ ║ ║ ║ ║ ║ ║ ║ ╙╢ ║ ╙╢ ║ ║ ╙╢ ║ ╙╢ ║╓╜ ║ ╙╢ ║ ╙╢ ╙╢ ║ ║ ║┌╫───╜ ║ ┌╢ ║┌╢ ║ ║┌╢ ║┌╢ ║ ║║ ┌╢ ║ ║ ║ ║ ║ ║ ║│║ ╓─╢ │║ ╓╢│║ ╓╢ ║│║ ╓╢│║ ╓╢ ║║ │║ ╓╢ ║ ║ ║ ╜ ╨ ╙┘╚═══╝ ╚═╛╚═══╝╙┘╚═══╝╙─╨┘╚═══╝╙┘╚═══╝║┌╜╙─┘╚═══╝╙─╜ ╨ ║ ╓────╫┘ ║ ╓─────────────────────────────────────────╚════╝──────────────────╜ ╙─── architecture (software foundation) SNAV - main documentation - 16.4.90 page 1 - ┌───────┐ ─────────>│ AVNER │ ─────────>│ BEN │──────> Software Engineering Method └───────┘ 10 Dov-Hoz st. Tel-Aviv 63416 Israel tel. 972-3-221535 ┌─────────────────────────────────────────────────┐ │ "The Screen NAVigator" │ │ │ │ THE C++ IMPLEMENTATION │ │ │ │ Version 1.10, April 1990. │ └─────────────────────────────────────────────────┘ Copyright (c) 1990 by Avner Ben. Written by Avner Ben 13 April 1990. Original written 28 November 1989. SNAV - main documentation - 16.4.90 page 2 - EPREFACEF E───────────────────────────────────────────────────────────────────────F The Screen NAVigator version 1.10 is implemented in 4 source files and 3 corresponding header files, named "snav0" Through "snav4". A make-file is supplied to compile these files and bind them into a library. The code was developed on an AT clone using the Zortech C++ compiler version 2.0. The distribution of the code to these 4 source files reflects a functional partitioning. Snav0 furnishes the most elementary level: a simple "geometry" of characters. It supplies the basic objects and operators on which the whole of the system draws. Snav1 supplies the (semigraphic) "alphabet" object. The data-structure it supplies allows the application to define semigraphic entities on the character level, and manipulate them in complete disregard to their machine-architecture, collating-sequence or console-device implementation. Snav2 is the beginning of a working application level. precisely, it supplies two generic entities that the user is expected to elaborate upon, and custom-tailor to his/her exact application, using the C++ implementation of polymorphism. These are the generic "panel" - a formatted output device, and the generic "shape" - an outline drawing using the semigraphic character set or course "typewriter graphics" (TWG). While the "shape" class complex is supplied as a complete application, which the user is expected to improve and extend, the "panel" class contains a "hollow compartment" (pure virtual methods), which the user must fill-in with the particulars of the various devices he/she may be manipulating in the real world. A complete, annotated listing of the classes, hidden data and enclosed methods is supplied in the three header files. The following documentation discusses the contents in nontechnical language. For a thorough study of the data structures involved and the logic behind their design, refer to file "article.prn". SNAV - main documentation E PREFACEF - 16.4.90 page 3 - -1Technical note.-0 The SNAV C++ implementation reflects many compromises in an attempt to ensure a minimal degree of machine efficiency in an overall partitioning that is absolutely object-oriented. Compromises apply to method implementation and hidden data redundancy. SNAV does not involve garbage collection; it attempts not to produce it (references that cannot be deallocated), at the cost of overhead, common with such design policies. The user should be aware of when functions receive and return by reference and when by value, and work his/her memory management policy accordingly. SNAV applications should have a good response time with fast 286 machines and above. On slow AT's and fast XT's a negligible delay may be apparent, compared with assembly-written drivers, but, for most applications, it will be acceptable. On slow XT's and PC-G's a noticeable delay may (not at all cases) become apparent. For the last 4 years, I have been running my own character-graphic utilities, based on early versions of SNAV, on a number of 4.77Mhz XT's, and have survived the performance. C++ does not compete assembler code in the field of performance. C++ code, on the other hand, achieves superior performance in the field of software maintenance. The SNAV code is generic. Once you register your copy, you may easily improve it, to suit your application. For example, by replacing machine-sensitive portions with inline assembly, a practice enabled by most modern C compilers. SNAV - main documentation - 16.4.90 page 4 - ENOTATIONF E───────────────────────────────────────────────────────────────────────F the following specification makes use of Object-Dependency Diagrams. ODD is a private notation developed by me in conjunction with Snav. For syntax specification, refer to file "notation.prn". SNAV - main documentation - 16.4.90 page 5 - ESNAV0 - CHARACTER GEOMETRYF E───────────────────────────────────────────────────────────────────────F ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ d4│ d16│ │d2 │d16 │ │ ┌────┴────┐ ┌───┴───┐ ┌───┴───┐ ┌────┴───┐ │ │ │direction│ │inter- │ ┌─>│ axis │ │weight_d│ │ │ └─────────┘ │section│ │ └───┬───┘ └────┬───┘ │ │ └───┬───┘ │ │ │ │ │ │ │ │ │ │ │ ├──────┘ └──┐ │ │ │ │ │ │ │ │ c4│ │ │ │ │ ┌────┴────┐ │ ┌────┴───┐ │ │ │direction│ └───>│ axis/ │ │ │ └─────────┘ │ weight │ │ │ └────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ Compatibility. Snav0 is the oldest part of the SNAV system. its logic is deeply researched and is well tested. Modifications due are likely to expand its scope and affect mainly the hidden internals of classes. Such changes are not likely to affect referencing code seriously, though some minor changes are possible. The user is warned never to use explicit integer values when initializing or modifying objects, limit the explicit usage of enumerated values, and count as much as possible on system-supplied defaults. SNAV - main documentation E SNAV0 - CHARACTER GEOMETRYF - 16.4.90 page 6 - -1DIRECTION.-0 The datatype "direction" has a domain of five values, represented internally by an integer. It is really an enumerated type with methods. The values correspond to the four directions of the plane, and the null direction. Methods are supplied for obtaining the names of these values. By default, an object of class direction is initialized to "Right", weighing 1 (being the most common direction in European language texts). Operators are supplied for "incrementing" and "decrementing" the value to obtain a succession of directions (the order is predefined). This makes possible such typical loops as: ┌─────────────────────────────────────────────────────────────────────┐ │ for (direction dir; dir(); dir++) // dir() returns integer value │ └─────────────────────────────────────────────────────────────────────┘ The values are incremented in powers of 2, to allow for bitwise arithmetic, and set operations in the more complex datatype "intersection". The bitwise arithmetic makes the application somewhat less conceptual, but has proven to reduce response time of the demo program in about 10%, over ordinary multiplication and division. Note that direction and intersection method references are the most frequent operations in a SNAV application, and their optimal performance must overcome design elegance. For convenience, snav0 predefines five objects of type direction, supplying the whole domain, (intended to be read only). Compatibility. Future versions of SNAV may expand the direction domain to acknowledge directions of the dimension of depth. Also, a scheme may be introduced to allow the user to define his/her direction ordering. Neither of these changes is expected to affect present applications seriously. SNAV - main documentation E SNAV0 - CHARACTER GEOMETRYF - 16.4.90 page 7 - -1INTERSECTION.-0 The datatype "intersection" is a bitwise implementation for a "set of directions". Its domain includes 16 values. An object of class intersection may "include" (but not physically yield), at any moment of its existence, between zero and four distinct directions. The intersection does not physically allocate the set of directions for reasons of machine efficiency. Anyway, the need for that does not come up in practice. This typically results in loops such as this: ┌─────────────────────────────────────────────────────────────────────┐ │ // given is intersection avdir (available directions) │ │ for (direction dir; dir(); dir++) │ │ if avdir>=dir ... // direction is included │ └─────────────────────────────────────────────────────────────────────┘ Supplied are the necessary set-theoretic operators for inclusion, exclusion and their test, on both member and subset level. Intersections are classified in "types", according to their internal organization, having functional significance in the semigraphic application, such as "corners", "forks", "arrowheads" etc. Methods for obtaining these types and their names are supplied. By default, an object of class intersection is initialized to all directions (type "cross"). Snav0 predefines a limited number of intersection objects, having to do with class "axis". Compatibility. All changes to the direction domain will naturally affect the intersection domain (being derived from it). SNAV - main documentation E SNAV0 - CHARACTER GEOMETRYF - 16.4.90 page 8 - -1AXIS.-0 "Axis" (or dimension) is a private case of intersection, including exactly two directions, that are held to be "opposite". Of the 16 intersections possible with the four directions of the plane, exactly 2 qualify for axis. These are called normally "horizontal" (weighing 1) and "vertical" (weighing 2), and sometimes "y" and "x". An obvious case for using an axis (rather than plain intersection or direction), is to measure the weight of a character. The need to generalize directions into an axis also arises when plotting or tracing an arc on the screen. ┌─────────────────────────────────────────────────────────────────────┐ │ // given is direction dir │ │ axis dim(dir); // allocates the axis on which dir is progressing │ └─────────────────────────────────────────────────────────────────────┘ Snav0 predefines objects for the axis domain, and the corresponding intersections. Compatibility. SNAV 1.10 implementation of axis assumes 2 dimensions, for machine efficiency. The addition of a third dimension may cause loss of performance, but no serious effect on current code. -1AXIS_WGT.-0 A technical datatype needed by weight_d. Stores the "weight" (line thickness) on an axis of the plane. Has no important methods, and is not normally referenced. SNAV - main documentation E SNAV0 - CHARACTER GEOMETRYF - 16.4.90 page 9 - -1WEIGHT_D.-0 The datatype "weight_d" (weight distribution) is the bridge between the abstract geometrical concepts defined so far and the more practical world of characters on the panel. It is also the first class dealt with so far, that internally allocates objects of another class, rather than a simple numeric code. An object of class weight distribution internally allocates a pair of axis/weight objects, storing the weight (line thickness), possibly of some character or class of characters, on each axis of the plane. Where characters are concerned, that obviously denotes the horizontal stroke and vertical stroke. In SNAV, Semigraphic characters are assumed to have an even weight distribution, and therefore, exactly two weights, one per axis. Obviously ,the combination of weight-distribution and intersection uniquely defines one semigraphic. for example: ┌─────────────────────────────────────────────────────────────────────┐ │ intersection avdir(RTDIR+LTDIR+DNDIR); // initialized by int value │ │ weight_d wgt(2,1); // initialized to double horizontal stroke │ └─────────────────────────────────────────────────────────────────────┘ has the potential to yield the character ╤ (we still need an "alphabet" class to generate it - see snav1). Four weights are assumed arbitrarily (expressing the pc extended ASCII code-set): 1 and 2 denote the semigraphic subset of the pc (or other "newcode") alphabet. 3 ("full") is used for the full-pixel character. 0 is used for "TypeWriter Graphics" (TWG) - the characters + - | <> V^, but only when combined to create rudimentary charts. Snav0 predefines objects for pc-useful weight distributions. Compatibility. All changes to the number of axes supported will naturally affect the internal storage of weight distribution. Added arguments will default to support a two-dimensional system as subset. SNAV - main documentation - 16.4.90 page 10 - ESNAV1 - CHARACTER GEOMETRYF E───────────────────────────────────────────────────────────────────────F ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │p* │ │ ┌───┴────┐ │ │ │computer│ │ │ │alphabet│ │ │ └───┬────┘ │ │ │ │ │ ┌──────────┴────────┐ │ │ d*│ c16│ │ │ ┌─┴──┐ ┌─────┴──────┐ │ │ ∙∙∙∙∙∙∙∙∙∙∙∙∙∙│char│ ∙∙∙>│intersection│ │ │ ∙ └─┬──┘ ∙ └────────────┘ │ │ ∙ ∙∙∙∙∙∙∙∙∙∙│∙∙∙∙∙∙∙∙∙∙ │ │ │ ∙ ∙ ┌──────┴─────┐ │ │ │ ∙ ∙ c│ c│ c16│ │ │ ∙ ┌─────┴──────┐ ┌───┴────┐ ┌───┴────┐ │ │ ∙ │intersection│ │weight_d│∙∙∙>│weight_d│ │ │ ∙ └────────────┘ └────────┘ └───┬────┘ │ │ ∙ │ │ │ ∙ │ │ │ ∙ │ │ │ ∙ ┌─┴──┐ │ │ ∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙>│char│ │ │ └────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ Compatibility. Any reference whatsoever to snav1 involves objects defined on snav0, so any change to the latter will affect it in the obvious way. Snav1 itself is a rather straightforward implementation of the general architecture needed to support a semigraphic alphabet on most current computers. A PC-oriented alphabet is supplied by default, which may be replaced or dynamically modified by the user. SNAV - main documentation E SNAV1 - CHARACTER GEOMETRYF - 16.4.90 page 11 - -1COMPUTER_ALPHABET.-0 An alphabet object consists of an array of weights and intersections (stored by integer value), where each pair defines the semigraphic qualities, if any, of the character bearing that number in the collating sequence in use. A method is supplied to "poke" values to the array, thus modifying the collating sequence during run-time. In addition, the alphabet constructor optionally takes a null-terminated integer array, specifying all the needed pokes in advance. The Constructor must receive the maximum number of characters to be used, including binary zero (256 in the pc example). This may not change. From this information, the alphabet allocates a cross-reference table, allowing fast retrieval of characters by semigraphic attributes, which is the main purpose of the SNAV system. The reference table is updated in real-time, reflecting any modification to the collating sequence. For example, a method is supplied for "inverting" the whole alphabet on a selected axis, for uses such as migrating from English to Hebrew in the middle of a sentence. Note that the alphabet has no copy operator, so each alphabet declared (normally referenced by pointer) must be initialized separately. Note that SNAV expects semigraphic-to-character assignments to be unique. No check is made to ensure that you do not assign the same attributes to two characters (by collating sequence number). The matching mechanism will come up with the match of lower ascii value, which may not always be what you may expect! The important alphabet methods deal with retrieval of characters from the present collating sequence, using separately prepared semigraphic attributes (weight and intersection), and with the opposite, querying the attributes of a given character. These methods may be combined to create continuous contour shapes, using semigraphics of various weights - see snav2. "Cdir" and "cweight" are low-level methods that retrieve character attributes. "Get_c" is a delicate mechanism for retrieving character by attributes. It tests a sequence of 6 search paths, from straightforward to less obvious alternatives, before it gives up (returning space). This mechanism is based upon long experience with live material. The user is warned not to modify it, unless in case of real emergency, because many higher level objects expect it to behave this way! "Translate" does the same working the specification from a sample character. SNAV - main documentation E SNAV1 - CHARACTER GEOMETRYF - 16.4.90 page 12 - Higher level methods deal with character "connectivity", where elements are considered two at a time. "Ccont" (Character CONTinues) tests if two characters connect in a given direction. it is the main primitive of semigraphic shape construction and recognition. "Carrw" (one Character in ARRoW) is the bridge between the technical alphabet and application world of shapes. Carrw suggests the next character in an "arc" (straight line), given its weight, general direction (In SNAV, everything is either moving in some direction or is not semigraphic), planned length, position and if it is pointed. The key argument is the "environment string", a type of argument used all over the system. This consists of five characters, number zero being the target character, and the other four its neighbors on the screen, their positions (1-4) determined by the order inherent in the direction datatype (obtained by direction::serial()). The user is warned not to use explicit integer values for constructing env. A typical method for constructing env is: ┌─────────────────────────────────────────────────────────────────────┐ │ // given position y:x on some screen, occupied by char c │ │ char env[6]; │ │ *env=c; │ │ for (direction dir; dir(); dir++) │ │ env[dir.serial()]=my_screen.get_neighbour(y,x,dir) │ │ env[5]='\0'; │ └─────────────────────────────────────────────────────────────────────┘ The method returns a character value to the user, who is then responsible for putting it in the desired place. "Cearrw" (carrw affecting Environment) is an extended version of carrw that "trims" inelegant "excess" of the neighbors, and makes some other nonlocal considerations. The user is expected to know where to put each of the elements in the string. Note that the method modifies its argument! Cearrw incurs a loss of response time, so make sure that you really need its improved esthetics. It is automatically used by the arc manager (snav2) if ENVMODIFY is #defined. Snav1 defines a default alphabet object, referenced by pointer. It includes an "in memory file" in the form of integer array, which it uses to initialize the object to the IBM-PC extended ASCII collating sequence. The user may then replace it with specific alphabet object(s), to suit the machine or application. Compatibility. Currently, the alphabet object has no facilities for generating its own character shapes, counting entirely on the host display device. This may force developers of pixel-oriented graphic software to extend the model to acknowledge their ability to generate their own characters. Future versions may include the ability to generate the semigraphic subset, possibly by downloading the definition to an external device, such as an EGA screen or printer. This may imply extensions to internal class architecture, and to the constructor. However, such modification is not expected to affect the methods concerned with character recognition and retrieval, using semigraphic attributes, (applying to most traffic to the alphabet object). SNAV - main documentation - 16.4.90 page 13 - ESNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF E───────────────────────────────────────────────────────────────────────F Panel: ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ p0│<∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙│p* │ │ ┌──┴──┐ ┌┴┐ │ │ │panel│ ┌─>│?│ │ │ └──┬──┘ │ └─┘ │ │ │ │ │ │ ┌───────────┬────┴────┬─────────┬────┘ │ │ │ │ d2│ │ │ │ ┌────┴────┐ ┌────┴────┐ ┌──┴──┐ ┌────┴─────┐ │ │ │point_pos│ │direction│ │color│ │square_pos│ │ │ └─────────┘ └─────────┘ └─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ d2│ │ │ ┌────┴────┐ │ │ │point_pos│ │ │ └─────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ Shape: ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ p*│<∙∙∙∙∙∙∙∙∙∙∙ │ │ ┌─┴─┐ ┌──┴──┐ ┌─┐ │ │ │arc│ │shape│ ┌──>│?│ │ │ └─┬─┘ └──┬──┘ │ └─┘ │ │ │ │ │ │ │ ┌─────────┼─────────┬─────────┐ ├──────┘ │ │ │ │ │ │ p*│ │ │ ┌──┴──┐ ┌────┴───┐ ┌───┴─────┐ │ ┌───┴──┐ │ │ │color│ │weight_d│ │direction│ └────>│stroke│ │ │ └─────┘ └────────┘ └─────────┘ └───┬──┘ │ │ │ │ │ │ │ │ │ │ │ ┌────┴────┐ │ │ │point_pos│ │ │ └─────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ SNAV - main documentation E SNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF - 16.4.90 page 14 - Compatibility. Unlike snav0 and snav1 that are based upon a theoretical foundation (see "article.prn"), snav2 is a first generation prototype (though by no means an improvisation). The art of building character-oriented screen drivers has little surprises to offer. The screen driver in snav1 (class "panel") draws from my experience in maintaining and writing character-oriented screen drivers in Fortran-4, Turbo-Pascal, ANSI-C and now C++. I am waiting for user responses to this particular design (see "bug report" attached to the registration form), to fine-tune it into a real "generic" class. The generic "shape" owes to the SNAV approach, that contour shapes are charted by cursor in motion, and given the snav0 and snav1 arsenal of objects (direction, intersection, axis, weight_distribution, alphabet), and their operators. Again, I am looking for user response, because I am not sure what applications people may find for it, and what effect applications I have not thought of may have on the basic design. When enough applicative information is gathered, I will reverse-engineer the logical schema from the prototype, and then reconstruct the code to suit the theoretical foundation. Until then, I cannot promise complete compatibility. SNAV - main documentation E SNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF - 16.4.90 page 15 - -1PANEL.-0 An object of class panel (must be referenced by pointer) may be any formatted output medium, wether static like a printed page or dynamic like a CRT screen, that can take characters, one at a time, so that each has a fixed position on the two axes of the plane, distributed evenly, like a matrix. This generic panel implementation does not support nonproportional spacing or varying font sizes. It is on a level definitely lower than the medium assumed by DTP software. The panel is assumed to be able to generate the appropriate character shape by its collating-sequence number, and retrieve the value of the character occupying each cell by y:x address, at any given moment. It is also supposed to manage colors (or visual "attributes") for these cells, in the same way. A snav panel is much like a "window", in being restricted to an oblong slice of a larger screen object, transparently managed by the hardware. Class "point_pos" is supplied to access cells on the panel. The whole window is specified by an object of class "square_pos", consisting of two points, specifying top-left and bottom-right corners. Also provided is struct "color_ind", grouping together visual attribute state variables. Color management follows the ANSI example. The attributes maintained are background color (enumerated on an 8 color scale), foreground color (same) and "attribute" (supported are high-intensity, reverse-video, blink, underline and invisible). A panel object manages a point_pos object for cursor position, a direction object for cursor direction, and a color_ind object for visual attributes. Cursor addressing is done using absolute hardware-screen positions. There is no facility for interpreting cursor addressing, relative to window start. Since the abstract panel leaves physical cursor positioning and reading to the implementation, cursor addresses outside panel bounds should be ignored at character-print/read level, in the physical driver implementation, using the method "ask_legal". The cursor-direction object is used in order to compute the next point, after a character "put" operation. By default, the cursor direction is initialized to "Right" (actually, the value that direction() is initialized to), but the user may change it during run-time, to acknowledge a Semitic or Asian language text, or for arc-processing. In each case, the cursor will behave accordingly (I am sure about the Semitic cursor. The "Asian" cursor is just a guess). Although the generic panel is expected to behave like a two-dimensional array, no assumption whatsoever is made as to its physical architecture. My private SNAV application works with half a dozen inherited screen types, one of them, a sparse matrix with variable length lines and unlimited size, used to edit pages for print, implemented by a host of pointers. Yet this formidable data structure answers the same methods as the simpleminded matrix CRT. SNAV - main documentation E SNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF - 16.4.90 page 16 - There are two ways to paint the panel, reflected by the use of pointer arguments for point and direction. If an explicit point is not specified (NULL argument), the cursor will be used (and advanced), and same goes for direction. Note that "direct cursor addressing" (specifying the arguments) leaves cursor and direction unchanged, and do not wrap around. The cursor, on the other hand, will wrap around at the end of the line (and bottom of screen), if setup by the method "toggle_wrap". The panel protocol consists of two levels. In the lower level are defined "virtual" methods, which are so device-specific that may never be defined to fit the general case. The second level offers "macros", of various complexity, taking the generic methods for granted. Because the use of polymorphism in C++ will not allow the user to refer to methods defined in the inherited class (and because the user must declare an inherited class, if he/she wants anything more than a heap of empty stubs), I have tried to include all nontrivial methods in the generic definition. However I did not include methods that assume a specific working procedure, such as newline. For a complete listing of the panel protocol, see snav2.hpp. For a sample implementation of a real-world device driver inheriting panel, see the sample application, demo1.hpp and demo1.cpp. An extra service supplied by the generic panel is "TWG" - TypeWriter Graphics conversion. The algorithm used (one of the only cases of long hard-to-follow code in the SNAV package) is a generalization of the line-oriented algorithm by that name, that I distributed in the PD in ordinary C, two years ago. Unlike the line-oriented version, the full-screen version can handle mixed TWG/semigraphic shapes, and is responsible for a somewhat more intelligent result (but is considerably slower, referring to the whole SNAV foundation). It does not account for the "fix" in line-oriented TWG, concerning open boxes. Twg's main function is to allow character-graphic charts to be transferrable to character sets that do not support real (connecting) semigraphic characters, such as most old ASCII 127 and EBCDIC "oldcode" implementations. It is also useful for fast-drawing semigraphic charts, if a few common-sense rules are observed. Experiment with the TWG option in the enclosed demo. The shapes you experiment on must be charted using the 0:0 weight distribution! SNAV - main documentation E SNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF - 16.4.90 page 17 - -1ARC.-0 Since SNAV deals with characters in motion, an object of class "arc" (straight line) stores only its direction (exactly one), weight distribution (exactly one, and only the relevant axis considered), length (in characters) and if it is pointed (version 1.10 does not support double-tipped arrows). Unlike many pixel-oriented graphic packages, the origin point is not stored. The arc is an abstract entity that may be listed starting at any given point, affecting whatever is logically implied on the following path. This concept may be demonstrated dramatically by experimenting with the "cut" and "paste" operations in the enclosed demo program. The method "list" is a gate on this side, for the real arc-list method, implemented within the generic panel (called "arclist"). The reason for this, is to maintain information hiding within class panel (at the cost of importing functionality). This ensures an absolutely device-independent drawing medium. The listing invokes the current alphabet's method "carrw" ("cearrw" if ENVMODIFY is #defined) in order to elegantly "weld" each semigraphic element to its immediate environment, if that too is semigraphic. In order to understand what semigraphic "welding" is, experiment with the enclosed demo program, drawing one of the regular shapes supplied, and then crossing it with arcs of arbitrary weights. If a color is specified with the arc, it used for drawing instead of the current screen color. Neighboring characters welded by cearrw calls are left in their own foreground color. Currently, welding does not apply to color. The current color is always replaced. -1STROKE.-0 Class stroke inherits class arc, making it a list member. This enables the creation of a semigraphic curve. Each arc listing proceeds from the exact point its predecessor stopped (to allow for "welding"). A "pen-down" toggle allows jumping over the drawing-board, where a discontinued shape is desired. Class stroke also has a point_pos used to denote offset from shape start, by some shape-building procedures. Note. stroke has no start-of-list pointer. It is naturally intended to be managed by the iterator-class "shape". The user's role ends with creating a stroke and "appending" it to some shape. Do not assign the same stroke to two shapes, because the shape's destructor will delete it! Compatibility. Some future release may account for the listing of strings of characters, perhaps in connection with arc listing (often, arcs are accompanied by caption text). This may have some effect on the internal structure of either arc of stroke. SNAV - main documentation E SNAV2 - THE GENERIC PANEL AND GENERIC SHAPEF - 16.4.90 page 18 - -1SHAPE.-0 Shape is a semi-generic entity, normally referenced by pointer. But, unlike the generic entity "panel", it contains primitives that are likely to be too simplistic for more regular or arbitrary shapes, and are therefore defines as "virtual" methods. Class shape's main role is to serve as iterator-class for class stroke. When a shape is created, it is initialized to either a user-supplied stroke-list, or to NULL. The user than "appends" strokes, be them individuals or chains, to the stroke-list. Append attempts to optimize the shape, by ignoring and/or unifying redundant strokes. The virtual methods "list" and "clear" scan the available stroke-list. The derived shape "oblong", brought in snav3 as an example, demonstrates a more elegant approach. Since oblong is a regular shape, only the relevant arcs are allocated, and listed twice, in opposite directions. The derived shape "zigzag" in demo3, is an example of a two-element pattern, listed in a loop. This process redundancy may save storage space for very large shapes, provided they have a programmable underlying logic. Compatibility. The current implementation of shape assumes it to be either chaotic or display a repeating pattern. Future releases may accommodate a shape that is made of subshapes. SNAV - main documentation - 16.4.90 page 19 - ESNAV3 - SHAPE RECOGNITIONF E───────────────────────────────────────────────────────────────────────F ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ p*│<∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙│p* │ │ ┌──┴──┐ ┌───┴───┐ │ │ │shape│ ┌──────>│tracing│ │ │ └──┬──┘ │ └───┬───┘ │ │ │ │ │ │ │ ├──────┘ ┌─────┴────┐ │ │ p*│ │ p*│ │ │ ┌──┴───┐ ┌────┴────┐ ┌───┴────┐ │ │ │stroke│ │point_pos│ │landmark│ │ │ └──────┘ └─────────┘ └───┬────┘ │ │ │ │ │ ┌──────┴─────┐ │ │ │ │ │ │ │ d2│ │ │ ┌────┴────┐ ┌─────┴──────┐ │ │ │point_pos│ │intersection│ │ │ └─────────┘ └────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ Compatibility. At the present release, pattern recognition is of experimental status. The implementation calls for much optimization, and further research into its logic. It is supplied as a demonstration of the principle. No compatibility promised. SNAV - main documentation E SNAV3 - SHAPE RECOGNITIONF - 16.4.90 page 20 - -1TRACING.-0 The general derived shape "tracing" is a procedural entity whose function is to generate arbitrary shapes, presumably scanned from "the real world". The tracing constructor is a "probe constructor". its function may be defined as follows: ┌─────────────────────────────────────────────────────────────────────┐ │ If there exists in the real world (screen) in the coordinates │ │ specified (point) something that you may take for a shape, copy it │ │ as best as you can. │ └─────────────────────────────────────────────────────────────────────┘ The additional data hidden in class tracing are technical, and are merely "working storage" for executing the scan, and have no significance once the constructor returns. Class tracing is the main primitive for applications involving semigraphic pattern recognition. For a typical application, see my ANSI editor "The Lecturer", where an early version of SNAV is used to automatically track semigraphic shapes on the screen, preserved for animation in the same scan order. Compatibility. The stroke-list built by an object of the current version "tracing" class, is highly unnormalized. It is a sequential scan (in direction() order), involving many unnecessary pen-jumps and broken lines. To demonstrate that, use the enclosed demo program to draw a fence-like shape all over the screen, then "cut" it, and then "paste" it, forcing your computer to its slowest speed. As you can see, the route the pen takes calls for optimization. Future releases may include tracing normalization and automatic recognition of some regular shapes. -1OBLONG.-0 Class oblong is supplied as an example for a "regular" shape. Since it is made of a repeating element with programmable underlying logic, only the essential pattern elements are stored in the shape. The complete shape is created during list-time by the overloaded lister. Oblong is also used by the "enframe" panel method in snav2.