home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / EPMATR.ZIP / ATTRIBUT.DOC < prev    next >
Text File  |  1989-07-06  |  27KB  |  547 lines
  1.  
  2.  
  3. Attribute Support
  4.  
  5.                                                               Jason Crawford
  6.                                                               June 3, 1989
  7.  
  8.          Much talk has been going around the industry about hypertext.  We do
  9.     not want to enter into any heated discussion on the issue, but we believe
  10.     that one of the basic ingredients of a hypertext system is the ability to
  11.     bind metainformation into text.  In its simplest forms this information
  12.     might simply be a flag that indicates that a section of the text is to
  13.     appear in a certain color or font when displayed.  In an advanced form
  14.     this information may refer to an action to take when the associated text
  15.     is manipulated.
  16.  
  17.          In order to turn some the armchair hypertext programmers into real
  18.     hypertext programmers, we have taken a first step by giving E macro pro-
  19.     grammers the ability to imbed information within their text.  We call
  20.     this first step "attribute support."
  21.  
  22.          In this initial release of we allow a macro application to request a
  23.     set of attribute "classes" to support its needs.  How the requested
  24.     attribute classes are used is determined by the application.  That
  25.     application need not worry about other applications using the same
  26.     attribute classes for other purposes since other applications will be
  27.     granted other attribute classes for their use.
  28.  
  29.          In this release of attribute support, only 256 attribute classes are
  30.     allowed.  Attribute class 0 is reserved for use as a wildcard or an error
  31.     flag.  Class 1 is now reserved for controling the displayed color of text.
  32.     Classes 2..63 are reserved for future internally supported uses, and the
  33.     remaining 192 attribute classes can be allocated to macro applications
  34.     through the allocate_attr() function.
  35.  
  36.          Once an application has been allocated an attribute class, "attribute
  37.     records" of that class can be inserted into the text of the document with
  38.     the insert_attribute statement.  The position of an attribute record is
  39.     generally specified with four coordinates:  fileid, line, column, and
  40.     offset.  The first three of these coordinates should already be well
  41.     understood by macro programers, but the fourth coordinate is new.  In this
  42.     initial version of attribute support, no attribute record or character can
  43.     occupy the exact same location, so the offset coordinate (which is either
  44.     negative or positive; but never zero) indicates whether the attribute
  45.     record is before or after the character of the specified column.  If
  46.     several attribute records exist at the same column, then the offset
  47.     coordinate also specifies the relative position of those attribute
  48.     records.  For example, lets say that we have a line of text in our
  49.     document as follows:
  50.  
  51.                This is my line of text.
  52.  
  53.     And let's say that there are three attribute records at the same
  54.     column as the "m" in the word "my", as follows:
  55.  
  56.                [arA][arB]m[arC]
  57.  
  58.     If this is the case, then the location of attribute record A is column 9
  59.     and offset -2. Attribute record B is at offset -1, and Attribute Record C
  60.     is at column 9 offset +1.
  61.  
  62.          Each attribute record has a class field, a value field, and a support
  63.     field.  The class field (as described above) is a flag that indicates what
  64.     kind of information the attribute record conveys.  The value field can
  65.     hold a value from 0..64k-1, and the meaning of the value field is defined
  66.     by the application that is supporting the attribute class specified in the
  67.     class field.  The support field conveys information that the editor can
  68.     use to provide internal support.  For example, an attribute records with a
  69.     class of COLOR, a value field of 30, and a support field of PUSH indicates
  70.     that the text following this record should be colored ????  (which
  71.     corresponds to a value of 30), and that that color should be used until a
  72.     corresponding COLOR POP attribute record is encountered in the text.
  73.  
  74.     In general, these attributes will not be visible to the user,
  75.     but they are accessable within the macro language [see "query_attribute"].
  76.  
  77.          An attribute class can follow one of many attribute models. An
  78.     attribute model defines the extent of influence of each attribute record
  79.     of each class using that attribute model.  The simplest attribute model is
  80.     the tag model.  An attribute record that has a class that uses a tag model
  81.     just denotes a position in a file. A typical usage would be to mark
  82.     the location of footnotes or hidden text.
  83.  
  84.          A second attribute model is what I will call a "set-until-next-set"
  85.     model. In this model, an attribute record rules over all the text
  86.     following itself and preceding the next attribute record in the document
  87.     that has the same class. For example, if one turns on font A
  88.     just before column 2 and turns on font B just before column 32, then
  89.     characters in columns 2..31 should have a font type of A, and  characters
  90.     after column 31 and characters after the present line should have a font
  91.     type of B.
  92.  
  93.          The Color class is the first internally supported attribute class in
  94.     E. Its purpose is to allow an application to control the color (foreground
  95.     only on PS/55's) of the text when displayed by E. The Color class
  96.     attributes use a push/pop attribute model.  The basic concept behind this
  97.     third model is that all text following an attribute that pushes a color
  98.     will appear in that color until a color-pop attribute record occurs.  Text
  99.     following a color-pop attribute record will be displayed in the same color
  100.     as the text that occured before the previous color-push attribute record.
  101.     Using this model, an application can nest several levels of color by
  102.     inserting several color-push attribute records in the text before a
  103.     color-pop attribute record.  If no color attributes appear in the text,
  104.     then the whole text appears in the default background color.  If, at a
  105.     certain point in the file, the number of pops occuring earlier in the file
  106.     is equal to (or higher than) the number of pushes, then the default color
  107.     is used until the next color push occurs.  If a color push attribute
  108.     record lacks a corresponding color pop attribute record, then the pushed
  109.     color will remain active until the end of the file.  The included demo
  110.     will attempt to clarify any confusion on the matter.
  111.  
  112.          As you play with push/pop modeled attribute classes, you will notice
  113.     that the push/pop model does not use the value field of a pop attribute
  114.     record.  This is because the pop record indicates that the last push
  115.     attribute record of the specified class should be popped (regardless of
  116.     its value).
  117.  
  118.          We think the push/pop model is a good one.  We encourage macro
  119.     programers to use the push/pop model for attribute classes that they
  120.     engineer because all support that we add for the color's push/pop model
  121.     can be used by applications using a push/pop model.
  122.  
  123.     [assert: at this point reader understands colors and push/pop, and binding]
  124.  
  125.          We have built attribute support so that copying, moving, and deleting
  126.     a character will take the same action on the attribute records bound to
  127.     that character as is done to that character.  To illustrate this, create a
  128.     line with a variety of color attributes.  Just begin editing the text.
  129.     Notice that if you deleted a character that had a Push-Color attribute
  130.     record with it, then the region after that character will revert to the
  131.     previous color rather than the color that was pushed at that character.
  132.     The same can be seen with moving, copying, and deleting marked regions,
  133.     but that may be more difficult to see.
  134.  
  135.          Although the push/pop model of attribute support is fairly
  136.     straightforward, we expect macro programmers to initially run into
  137.     some complications.
  138.  
  139.          One of these complications is crossing of attribute pairs of the same
  140.     class.  The push/pop model only supports "imbedding" of regions within
  141.     other regions.  If one tries to specify two "overlapping" regions with
  142.     attribute records of the same class, one will run into problems because the
  143.     new and old attribute records will be interpretted by other applications
  144.     as imbedded regions.  If it becomes necessary to have overlapping regions
  145.     of the same class, then an alternative attribute model should be designed.
  146.     [Demo this one.]
  147.  
  148.          A second inconvenience that the macro programmer will face is the
  149.     lack of support for attribute strings.  This means that the insertline and
  150.     replaceline statements only insert attributeless lines into a file, and
  151.     the getline statement will only fetch the text of a line.  The typical
  152.     solution to this problem is to use copy, move, and delete actions on
  153.     marked regions rather than insertline's, replaceline's, and getline's.
  154.  
  155.          A third dilemna is that attribute support is provides an API;
  156.     but no user interface. We expect that macro programmers will be facing
  157.     many dilemna. For example, "What should be done
  158.     with attributes attached to a character that the user wants to remove or
  159.     replace?"  This is a user interface dilemna.  Simply deleting the
  160.     character and all its associated attribute records may not provide the
  161.     best user interface because if the attribute records for a character were
  162.     deleted, and one of those attributes had a color CLASS (using a push/pop
  163.     model), then the color of almost all text from that character to the EOF
  164.     will change.  [See Demo ???] This is probably not what was the user intended,
  165.     but deciding what was intended is not necessarily easy.
  166.          This version of attribute support does not attempt to make such
  167.     decisions.  Instead, it leaves such decsions to macro programmers, so that
  168.     the community of macro programmers can experiment with serveral user
  169.     interfaces.  In a few weeks we expect several UI's will emerge, and we
  170.     will begin supporting them.
  171.  
  172.          This version of attribute support allows a maximum of 255 attributes
  173.     per line.  Any attempt to add more attributes than 255 attributes will
  174.     result in a truncation error being flagged.  Similarly, shifting any
  175.     attribute beyond column 255 will result in a truncation error being
  176.     flagged and the truncated attribute record being lost.
  177.  
  178.         This first version of attribute support does not provide any means for
  179.     saving attributes in a file. Such functionality can be expected in
  180.     upcoming versions of EPM when OS/2 1.2 becomes more readily available.
  181.     Until that time, macro programmers can obtain (undocumented) macros from
  182.     JASON at YKTVMV that support the loading and saving of files and their
  183.     attributes under OS/2 1.1.
  184.  
  185.         Lastly, EPM is in a rapid state of flux. This is especially true of
  186.     attribute support. Any documentation provided for attribute support is
  187.     likely to become quickly outdated. Therefore macro programmers should
  188.     monitor the EPM FORUM on the IBMPC conference disk to get the most
  189.     up-to-date information.
  190.  
  191. The Classes
  192.  
  193.         This version of attribute supports several predefined attribute
  194.     classes to various extents:
  195.  
  196.     COLORCLASS
  197.         This attribute class can be used to color regions of text. The color
  198.         used is determined by the value field of attribute records of this
  199.         class. The values should be the same as those used for CGA monitors
  200.         except that "flashing" is not supported.
  201.  
  202.     HIDNCLASS
  203.         Attribute records of this class act as tags that flag the location of
  204.         text that is hidden. At the moment, hidden text is text that has been
  205.         temporarily hidden. This is implmented by a set of macros that move
  206.         the text to a hidden file. For further details, please refer to the
  207.         macros provided with attribute support.
  208.  
  209.         This class is currently only experimental, so please feel to modify
  210.         the supporting macros if you want to do some experimenting of your
  211.         own. If you come up with something clever, please let the rest of us
  212.         know.
  213.  
  214.     ASSOCCLASS
  215.         Attribute records of this class flag the existance of an associated
  216.         string. This class is helpful when implementing buttons within a
  217.         document (see BUTTONCLASS), and it could be used by a spell checker
  218.         for remembering alternate spellings or by a voice recognition system
  219.         for remembering probable alternate interpretations. For further
  220.         details, please refer to the macros provided with attribute support.
  221.  
  222.     BUTTONCLASS
  223.         This attribute class delimits a region (with the push/pop model) that
  224.         should be associated with a command. This attribute class works in
  225.         conjuntion with the ASSOCCLASS attribute class. For further details
  226.         see the BUTTONS.E file provided with this package.
  227.  
  228.  
  229. Attribute Statements
  230.  
  231.     The Attribute Support API consists of two macro language statements:
  232.     attribute_action, insert_attribute, and query_attribute.
  233.  
  234.     Query_Attribute
  235.                    this statement allows a macro program to deterine what
  236.                    attribute record can be found at the specified location.
  237.  
  238.          var Class
  239.                    returns the class of the found attribute record. A value of
  240.                    zero is returned if no attribute was found. A value between
  241.                    1 and 63 is returned if an internally supported attribute
  242.                    record was found. A value from 64 to 255 is returned if an
  243.                    application supported attribute record was found. The
  244.                    meaning of an application supported attribute record is not
  245.                    predictable at compile time. Some administrative macros
  246.                    will be provided for determining the meaning of a macro
  247.                    during runtime.
  248.  
  249.          var Value
  250.                    returns the value of the found attribute record. Its value
  251.                    is unchanged if no attribute record was found at the
  252.                    specified location.
  253.  
  254.          var IsPush
  255.                    returns the value of the support field of the found
  256.                    attribute. This parameters value is unchanged if no
  257.                    attribute record was found at the specified location.
  258.  
  259.          Offset
  260.                    The offset of the position being queried. Zero is an
  261.                    illegal offset. A negative value indicates a position
  262.                    before the specified character location, and a positive
  263.                    value indicates a value to the right of the specified
  264.                    character location.
  265.  
  266.                       ...[ar-2][ar-1][char][ar+1]...
  267.  
  268.          Column
  269.                    The column number of the position being queried.
  270.  
  271.          Line
  272.                    The line number of the position being queried.
  273.  
  274.          ViewID    (optional)
  275.                    The fileid of the position being queried. If unspecified,
  276.                    the current file will be assumed.
  277.  
  278.  
  279.  
  280.     Insert_Attribute
  281.                    this statement (non destructively) inserts an attribute
  282.                    record at the specified location.
  283.  
  284.          Class
  285.                    The class of the attribute record to be inserted.
  286.  
  287.          Value
  288.                    The value field of the attribute record to be inserted.
  289.  
  290.          IsPush
  291.                    The support field of the attribute to insert.
  292.  
  293.          Offset
  294.                    The offset of the position being queried. Zero is an
  295.                    illegal offset. A negative value indicates a position
  296.                    before the specified character location, and a positive
  297.                    value indicates a value to the right of the specified
  298.                    character location.
  299.  
  300.                       ...[ar-2][ar-1][char][ar+1]...
  301.  
  302.                    If an offset is specified that is greater than the largest
  303.                    offset of an attribute record at the specified column, then
  304.                    the attribute record is placed at an offset directly to the
  305.                    right of the attribute record with the greatest offset. The
  306.                    only exception to this rule is when there are no attribute
  307.                    records with positive offset at the specified column. In
  308.                    that case, the attribute record is placed at offset 1.
  309.                    Similarly, if a negative offset is specified that is less
  310.                    (more negative) than the smallest offset of an attribute
  311.                    record at the specified column, then the new attribute
  312.                    record is placed at an offset that is one less than the
  313.                    smallest offset.
  314.  
  315.                    If an attribute record already exists at the specified
  316.                    offset, then the old attribute record (and any attribute
  317.                    records at an offset of larger magnitude) is shifted to an
  318.                    offset of greater magnitude to vacate the specified
  319.                    offset for the new attribute record.
  320.  
  321.  
  322.          Column    (optional)
  323.                    The column number where the new attribute record should be
  324.                    placed. If this parameter is omitted, the current column of
  325.                    the cursor is assumed.
  326.  
  327.          Line      (optional)
  328.                    The line number where the new attribute record should be
  329.                    placed.  If this parameter is omitted, the current line
  330.                    number of the cursor is assumed.
  331.  
  332.          ViewID    (optional)
  333.                    The fileid of the file where the new attribute record
  334.                    should be placed. If this parameter is omitted, the active
  335.                    file is assumed.
  336.  
  337.  
  338.     Attribute_Action
  339.                    this statement is actually several statements. The
  340.                    first parameter determines what action is executed. We put
  341.                    several actions on this statement in order to conserve
  342.                    opcodes. Each action will be described in turn.
  343.  
  344.     Attribute_Action FIND_NEXT_ATTR_SUBOP
  345.                    This action finds the next occurance (not including the
  346.                    specified location) of an attribute record of the specified
  347.                    class.
  348.  
  349.          var Class
  350.                    input
  351.                       This specifies the attribute class of the attribute
  352.                       records of interest. A value of ANY_CLASS (zero)
  353.                       indicates that the position of the next attribute record
  354.                       of any class should be returned.
  355.                    output
  356.                       The class of the found attribute. A class of zero
  357.                       indicates that no attribute record was found.
  358.  
  359.          var Offset, var Column, var Line
  360.                    input
  361.                       These parameters specify the location (non-inclusive)
  362.                       where the search is to begin.
  363.                    output
  364.                       These parameters specify the location of the found
  365.                       attribute record. If none was found, then none of these
  366.                       parameters will be modified.
  367.  
  368.          var FileId (optional)
  369.                    The fileid of the file where the search is to occur.
  370.  
  371.  
  372.     Attribute_Action FIND_PREV_ATTR_SUBOP
  373.                    This action is just like the FIND_NEXT_ATTR_SUBOP except
  374.                    that it finds the previous occurance of an attribute record
  375.                    of the specified class rather than the next occurance.
  376.  
  377.     Attribute_Action FIND_MATCH_ATTR_SUBOP
  378.                    This action finds the (push/pop model) attribute record
  379.                    that matches the specified attribute record. For example,
  380.                    if a push attribute record was specified, the location of
  381.                    the corresponding pop attribute record is returned.
  382.  
  383.          var Class
  384.                    unused parameter.
  385.  
  386.          var Offset, var Column, var Line
  387.                    input
  388.                       These parameters specify the location (non-inclusive)
  389.                       where the search is to begin. An attribute record must
  390.                       exist at this location or an error code will be flagged.
  391.  
  392.                    output
  393.                       These parameters specify the location of the found
  394.                       attribute record. If none was found, then none of these
  395.                       parameters will be modified.
  396.  
  397.          var FileId (optional)
  398.                    The fileid of the file where the search is to occur.
  399.  
  400.     Attribute_Action DELETE_ATTR_SUBOP
  401.                    Deletes the attribute record at the specified location. If
  402.                    attribute records exists at the specified character
  403.                    position having an offset of the same sign as the specified
  404.                    attribute record but of larger magnitude, then those
  405.                    attribute records will be shifted in (their offset will be
  406.                    incremented or decremented) to fill in the vacated
  407.                    location.
  408.          var Class
  409.                    input
  410.                       unused input parameter.
  411.                    output
  412.                       The class of the deleted attribute record. Zero if no
  413.                       attribute record exists at the specified location.
  414.  
  415.          var Offset, var Column, var Line
  416.                    The location of the attribute record to be deleted.
  417.  
  418.          var FileId (optional)
  419.                    The fileid of the file where the specified attribute
  420.                    record is to be found.
  421.  
  422.  
  423.  
  424. Demo
  425.  
  426.    Several "GeeWhiz" demos are provided with this package in order help
  427.    people realize the capabilities of attribute support. (Tutorials are
  428.    also provided for educational purposes.)
  429.  
  430.    Demo 1 - EPM Calc
  431.           This demo simulates a reverse Polish notation calculator.
  432.        It also provides good sample code of the use of buttons.
  433.  
  434.        Instructions
  435.           1) Compile BUTTONS.E, ATTR.E, EPMCALC.E, and HIDEIT.
  436.           2) Start EPM
  437.           3) Issue the command "LINK EPMCALC"
  438.           4) Wait a moment for a calculator to appear
  439.           5) To "press" the calculator's buttons, move the
  440.               pointer over the button to be pressed, hold
  441.               down the Alt key, and double click on the
  442.               left mouse button.
  443.  
  444.        Advanced Instructions
  445.           6a)
  446.              Do a block mark of the calculator. Now duplicate
  447.              it. Notice that both calculators work
  448.              independently. This is because each instances
  449.              state information is stored in the file with it's
  450.              graphic representation. (See EPMCALC.E)
  451.           6b)
  452.              Do a block mark on a button. Duplicate it outside the
  453.              calculator. Notice that the button still works. Now
  454.              move (if you have done 6a) the button close to another
  455.              calculator. Notice that it now acts upon this second
  456.              calculator rather than its original calculator. This
  457.              is because EPMCALC's buttons apply their action on the
  458.              nearest calculator. (See EPMCALC.E)
  459.           6c)
  460.              Color the calculator by block marking it,
  461.  
  462.  
  463.        The Code
  464.           FindCalc
  465.  
  466.    Demo 2 - Highlight Phrase
  467.  
  468.        Instructions
  469.           1) Compile ATTR.E.
  470.           2) Start EPM
  471.           3) Issue the command "LINK ATTR"
  472.           4) Edit an interesting file.
  473.           5) Highlight all occurances of a phrase. This
  474.              can be done by invoking the HIGHLIGHT_PHRASE
  475.              command with the word to be highlighted as
  476.              the first argument.
  477.           6) The default color is 93. An alternate color
  478.              can be selected by giving a second argument
  479.              in the range of 0 to 255.
  480.  
  481.        Advanced Instructions
  482.           7)
  483.              The HIGHLIGHT_IDENTIFIER command may be more
  484.              useful when attempting to highlight all occurances
  485.              of an identifier in a Pascal, C, or E program.
  486.           8)
  487.              Highlight a many words in a paragraph using this
  488.              method. Change the margins, and reflow the
  489.              paragraph.
  490.  
  491.    Demo 3 - Hide C Blocks
  492.  
  493.        Instructions
  494.           1) Compile ATTR.E, CBLOCK.E and HIDEIT.E.
  495.           2) Start EPM
  496.           3) Issue the command "LINK CBLOCK"
  497.           4) Edit a .C file.
  498.           5) Place the pointer over a { character.
  499.           6) Ctrl-Right-DoubleClick
  500.           7) Notice that logical block that was delimited by
  501.              by the clicked '{' (and it's matching '}') was
  502.              compressed.
  503.           8) Place the pointer on the green '*'.
  504.           9) Alt-Right-DoubleClick.
  505.           10) Notice that the "hidden" block has reappeared.
  506.  
  507.        Advanced Instructions
  508.           11) Same as above, but try to imbed hidden regions.
  509.           12) For further details see CBLOCK.E.
  510.  
  511.    Tutorial 1 -
  512.        Demo 2 is really simple. Just look at the code for
  513.        HIGHLIGHT_PHRASE in ATTR.E.
  514.  
  515.    Tutorial 2 - Complications of attributes
  516.        1) Mark a region of a file. Preferably "CHAR" mark.
  517.        2) invoke "set_marked_region_to_color 43"
  518.        3) Unmark the region.
  519.        4) Notice that the formally marked region now
  520.            appears a different color. (Color 43).
  521.        5) Continue doing step 4.
  522.        6) Experiment with insertion of characters, deletion,
  523.             mark copies, mark moves, etc. of attributes.
  524.  
  525.    Tutorial 3 - Making a button
  526.        1) link in BUTTONS.EX
  527.        2) Block mark a large region.
  528.        3) Fill that region with spaces by invoking
  529.                "FILL"
  530.        4) Draw a border in the mark by invoking
  531.                "NICE_BOX"
  532.        5) Put the words "List files" in the button box
  533.        6) Block mark the button again.
  534.        7) Associate the "dir" command with the button by invoking
  535.               "associate_phrase_with_mark 4 DIR"
  536.        8) Block mark the button region.
  537.        9) Color the button by invoking
  538.               "set_marked_region_to_color 43"
  539.        10) Now we have a colored button with a border that
  540.               should execute a "dir" command when it is
  541.               pressed.
  542.        11) Enable the mouse for button depression by invoking
  543.               "enable_attr_keys"
  544.        12) Move pointer over the button.
  545.        13) Alt-Left-DoubleClick
  546.  
  547.