⟦4e98cb6e5⟧

E3 Source Code



package Editor_Interface is

    pragma Subsystem (Core_Editor);
    pragma Module_Name (4, 2010);


    -- A simple and very limited programmatic interface to the editor.
    -- It operates at the same level as the package !Commands.Editor,
    -- except it is more convenient to write programs against (as
    -- opposed to binding keys).


    -- a reference to a particular window on a particular image.
    type Image_Handle is private;
    Null_Image_Handle : constant Image_Handle;

    function Is_Valid (The_Image : Image_Handle)  return Boolean;
    function Hash     (The_Handle : Image_Handle) return Long_Integer;

    type Point is
        record
            Line   : Natural;
            Column : Natural;
        end record;
    Null_Point  : constant Point := Point'(Line => 0, Column => 0);
    First_Point : constant Point := Point'(Line => 1, Column => 1);


    -- Exceptions: some procedures below raise exceptions in error
    -- conditions. In this case the action requested is not attempted,
    -- but no error message is given to the user.

    -- Raised as indicated below when the calling program is not
    -- running in the foreground.
    User_Interrupted : exception;

    -- Raised on unindentified internal problems
    Internal_Error : exception;

    -- Raised on attempts to modify read-only or busy buffers.
    Read_Only_Error : exception;

    -- Raised on attempts to modify protected regions (such as in
    -- the mail oe)
    Protection_Error : exception;


    package Image_Access is
        -- Get the handle for a the image containing the user's cursor.
        -- can raise User_Interrupted.
        function Get_Handle return Image_Handle;

        -- Name of the Oe that owns this image.
        -- It is generally bad practice to depend too heavily
        -- on the string value returned here.
        function Oe_Name (The_Image : Image_Handle) return String;

        -- Name of this image. Often this corresponds to the
        -- Directory object represented by the image, but this is
        -- not guaranteed. The name is not neccessarily unique.
        -- If running in the background, there is a small chance the
        -- name will change sometime after the call.
        function Image_Name (The_Image : Image_Handle) return String;

        -- Returns cursor position on the window indicated by the handle
        function Get_Cursor (The_Image : Image_Handle) return Point;

        -- Return the beginning and end points of the selection, if it
        -- is on the window indicated by the handle. Otherwise return
        -- null points.
        procedure Get_Selection (The_Image   :     Image_Handle;
                                 First, Last : out Point);

        -- Returns the last point in the image.
        function Bottom (The_Image : Image_Handle) return Point;

        -- Put the users cursor at point, and make that point visible.
        -- Could raise User_Interrupted.
        -- If Cursor.Line or Column is 0 then raises Constraint_Error.
        procedure Set_Cursor (The_Image : Image_Handle; Cursor : Point);


        type Designation        is (Text, Prompt, Protected);
        type Designation_String is array (Positive range <>) of Designation;
        type Line_Contents (Length : Natural) is
            record
                Designations : Designation_String (1 .. Length);
                Text         : String (1 .. Length);
            end record;

        -- Return the contents of indicated line.
        -- Could raise User_Interrupted.
        -- If Line is past the end of the file, returns the empty contents
        -- (length = 0).
        function Contents_Of (The_Image : Image_Handle; Line : Positive)
                             return Line_Contents;

        -- Replace a portion of the text for a line.   Side effect of
        -- this operation will be to move the cursor.
        -- Could raise User_Interrupted, Read_Only_Error,
        -- Protection_Error, or Constraint_Error (if P.Line or Column
        -- is 0).
        -- The modification behaves much as if the user typed it:
        -- The half-plane model is respected (if P is past the end of the
        -- file or past the end of a line, empty lines or blanks (respectively)
        -- are inserted. Note the if the line or column of P is very
        -- far from the edge of the buffer, massive amounts of disk space
        -- will be consumed in this process).
        -- Prompts will be deleted as neccessary. Note this implies that
        -- the number of characters actually deleted may be greater than
        -- Old_Length, and that the first point of the resulting text may be
        -- before P in the image-- it may even be on a earlier line.
        -- After the call P will indicate the place where the insertion
        -- actually took place, which will differ from the value of P
        -- P before the call in the case of prompts.
        -- It is the responsibility of the caller to give the user
        -- an error message when exceptions are raised.
        procedure Replace_Text (The_Image  :        Image_Handle;
                                P          : in out Point;
                                Old_Length :        Natural;
                                New_Text   :        String);
    end Image_Access;


    -- An underline spans Length characters from Start.  Underlines
    -- may overlap, but cannot extend past a line, or span more than
    -- one line.  The Value is a piece of information put by the
    -- underliner that can be used by the underline coupler to process
    -- the underline when the Explain procedure is called
    type Underline is
        record
            Start  : Point;
            Length : Natural;
            Value  : Long_Integer;
        end record;
    Null_Underline : constant Underline :=
       Underline'(Start => Null_Point, Length => 0, Value => 0);


    -- This generic is used to put underlines on the image.  The instan-
    -- tiator's Explain procedure will get called when the Explain button
    -- is pressed with the cursor on an underline made by it.
    -- WARNING:  The instantiator's Explain procedure is called on a
    --           session thread (a task that is associated with the
    --           user's session), and could cause the user's session
    --           to lock up if it deadlocks or goes into an infinite
    --           loop.  It is expected that the Explain procedure will
    --           do simple and cheap operations when called, like give
    --           a simple message with the explanation.
    generic
        -- This procedure gets called when the Explain button is pressed.
        with procedure Explain (The_Image : Image_Handle; U : Underline);
    package Underline_Manager is

        -- Makes a new underline in Image.  Also puts in the coupler
        -- key for the instantiation in with the underline.  This will
        -- be used to call Explain.  Cursor is not moved.
        procedure Make (The_Image : Image_Handle; U : Underline);

        -- Removes underlines which overlap the region between First and
        -- Last (both inclusive).  All underlines upto a certain point can
        -- be removed by making First as First_Point, and Last as the des-
        -- ired point.  Likewise all underlines from a certain point can
        -- be removed by making First the desired point, and Last the bot-
        -- tom of the image (Image_Access.Bottom).  If Last precedes First,
        -- this is a no-op.
        procedure Remove
                     (The_Image : Image_Handle; First : Point; Last : Point);

        -- Returns the earliest starting point of all of the underlines
        -- that enclose P.  Could return Null_Point if none.
        function Enclosing_Start
                    (The_Image : Image_Handle; P : Point) return Point;

        -- Enables instantiator to process underlines traversing forwards
        -- or backwards in the image.  From indicates the point in the image
        -- where the traversal is to start and is included in the search.
        -- If the Skip_Rest out parameter is True, subsequent searching is
        -- terminated.  The user can pass information needed by Process_
        -- Underline in the User_Information limited private type.
        generic
            type User_Information is limited private;
            with procedure Process_Underline
                              (U         :        Underline;
                               User_Data : in out User_Information;
                               Skip_Rest : out    Boolean);
        procedure Process_Underlines (The_Image :        Image_Handle;
                                      From      :        Point;
                                      Forwards  :        Boolean;
                                      User_Data : in out User_Information);
    end Underline_Manager;
end Editor_Interface;
DataMuseum.dk

Rational R1000/400

⟦4e98cb6e5⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
