generatormessagesgrid.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2000-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit GeneratorMessagesGrid;

{The custom grid ~[link TGMGrid] to show the messages of the generators is
 defined in this unit.
}

interface

uses Windows, Messages, Classes, Graphics, Forms, Controls,
     StdCtrls, Grids, Menus,
     UGenerationMessages, GeneratorMessagesUtilities;

type

  //the options of the grid
  TGMGridOption = (
                   //show vertical lines between rows
                   goVertLine,
                   //show horizontal lines between columns
                   goHorzLine,
                   //always select the whole row instead of single cells
                   goRowSelect,
                   //move the mouse pointer inside the current column when
                   //moving a column and it is outside of the moved column
                   //after the exchange of two columns
                   goMoveCursorOnCol,
                   //whether the width of the title of a column should also be
                   //included when checking the maximum width of a column when
                   //automatically resizing it
                   goAutoSizeColumnsWithTitle,
                   //whether the fixed header row should be filled to span the
                   //whole top of the control
                   goFillFixedRow,
                   //whether the size of the "thumb" of the scroll bars should
                   //be changed to represent the relative size of the shown
                   //part that canbe scrolled
                   goScrollBarThumb,
                   //whether rows can quickly be searched by selecting the
                   //column to search in and typing the beginning of the text
                   //to search for
                   goQuickSearch);


  //the options of the grid
  TGMGridOptions = set of TGMGridOption;

  //how the title of the columns should be shown
  TShowTitle = (
                //don't show the titles
                stNone,
                //show only a minimal bar, to allow resizing and moving of
                //the columns
                stMini,
                //show the whole title cells including the title for the
                //columns
                stText);

      //the names/captions/titles of the options of the grid
const TGMGridOptionCaptions : array[TGMGridOption] of String =
                              ('Vertical Lines', 'Horizontal Lines',
                               'Whole Row', 'Move Pointer',
                               'Auto-Size Columns with Title', 'Fill Header',
                               'Sized Scroll Bar Thumbs', 'Quick Search');

type
  //current input state of the grid, this means the mouse input
  TGMGridState = (
                  gsNormal,      //idle, no special action
                  gsSelecting,   //the user is selecting cells
                  gsColSizing,   //the user is resizing a column
                  gsColMoving);  //the user is moving a column

  //the content of the columns in the grid
  TGMColumnShowed = TGeneratorMessageFieldView;

  //the array to hold the widths of the columns by their types
  TGMColumnTypWidths = array[TGMColumnShowed] of Integer;
  //a map from the index of a column to the type of its content
  TColumnToGMColumnType = array[Ord(Low(TGMColumnShowed))..
                                Ord(High(TGMColumnShowed))] of TGMColumnShowed;

  //used to define a simple order to sort the data of the grid by
  TGMSortOrder = record
                   //the field to sort by
                   Field: TGMColumnShowed;
                   //the direction to sort the field,
                   //+1 for ascending or -1 for descending
                   Direction: Integer;
                 end;
  //a complete sort order with multiple sort fields
  TGMSortOrders = array[Ord(Low(TGMColumnShowed))..
                        Ord(High(TGMColumnShowed))] of TGMSortOrder;

  {Event procedure to be called when a cell of the grid is being selected.
  ~param Sender    the sender of the event, the grid
  ~param Index     the index of the selected row
  ~param Column    the index of the selected column
  ~param CanSelect out: whether the cell can be selected; default is true }
  TGMSelectFieldEvent = procedure (Sender: TObject; Index: Integer;
                                   Column: Integer;
                                   var CanSelect: Boolean) of object;
  {Event procedure to be called when a title of a column is being clicked or
   double clicked.
  ~param Sender the sender of the event, the grid
  ~param ACol   the index of the clicked column }
  TGMFixedClick = procedure (Sender: TObject; ACol: Integer) of object;

  //a coordinate of a cell inside the grid
  TGMGridCoord = TPoint;
  //the coordinates a range of cells inside the grid
  TGMGridRect = TRect;


  {This is a customized grid to show the messages of the generators.~[br]
   It is more or less a custom implementation of a ~[code TDrawGrid]. Each
   message will be represented as a row, each column shows one field of the
   messages, the columns can be moved and resized and the field to be shown can
   be selected for each column, new columns can be added or useless ones
   removed. The messages can be sorted, for this reason only their indices are
   saved and sorted in the array ~[link FShownIndices], mapping an index of a
   row the index of the message in the list ~[link FMessageList]. }
  TGMGrid = class(TCustomControl)
  private
    //the style of the border of the control
    FBorderStyle: TBorderStyle;
    //whether and what scroll bars of the grid should be shown
    FScrollBars: TScrollStyle;
    //the options of the grid
    FOptions: TGMGridOptions;
    //the default width of columns in the grid
    FDefaultColumnWidth: Integer;
    //the height of the rows showing the messages
    FRowHeight: Integer;
    //the image list containing the images to indicate the current sort order
    //of the grid
    //~see FImageIndices
    FImageList: TImageList;
    //the indices of the images in the ~[link FImageList] indicate the current
    //sort order of the grid
    FImageIndices: array[Boolean] of Integer;

    //the list of the messages to be shown in the grid
    FMessageList: TGeneratorMessageList;
    //the descriptions of the messages
    FMessageDescriptions: TMessageDescriptionsList;
    //the indices of the messages in the order to be shown
    FShownIndices: array of Integer;


    //the currently selected cell
    //~see FAnchor
    FCurrent: TGMGridCoord;
    //the cell where the selection has been started;
    //if different from ~[link FAnchor], a range of cells has been selected
    FAnchor: TGMGridCoord;
    //the cell to be shown at the top left position of the grid
    FTopLeft: TGMGridCoord;

    //the number of shown columns in the grid
    FColCount: Integer;
    //the currently shown columns
    FColumns: TColumnToGMColumnType;
    //the width of each column in the grid, initialized by
    //~[link FDefaultColumnWidth]
    FColWidths: TGMColumnTypWidths;

    //the number of rows in the grid
    FRowCount: Integer;
    //whether and how the title of the columns should be shown
    FShowTitle: TShowTitle;
    //the height of the first row with the titles
    FTitleHeight: Integer;


    //the number of fields in ~[link FSortOrder] to sort the messages by
    FSortCount: Integer;
    //the order in which the messages should be shown, the number of valid
    //entries in this list is determined by ~[link FSortCount]
    FSortOrder: TGMSortOrders;

    //the event handler to be called when a column heading is clicked
    FOnFixedClick: TGMFixedClick;
    //the event handler to be called when a column heading is double clicked
    FOnFixedDblClick: TGMFixedClick;
    //the event handler to be called when a cell in the grid is being selected
    FOnSelectField: TGMSelectFieldEvent;
    //the event handler to be called when the grid is scrolled and other
    //messages or fields are shown
    FOnTopLeftChanged: TNotifyEvent;

    //used to optimize changing the mouse pointer when hovering in the title
    //row between two columns (i.e. to indicate the column can be resized);
    //this optimization saves the message handler to request the position of
    //the mouse pointer again
    FHitTest: TPoint;
    //if there is only one column, the vertical scroll bar will scroll through
    //the width of the column, instead of scrolling through the number of
    //columns, this is the offset inside the sole column
    FColOffset: Integer;

    //current input state of the grid
    FGridState: TGMGridState;

    //the last quick search within a column of the grid
    FLastQuickSearch: String;
    //the last field a quick search was done on
    FLastQuickSearchField: TGMColumnShowed;


    //Returns the width of the grid used by its columns.
    function GetGridWidth: Integer;
    //Returns the height of the grid used by its rows.
    function GetGridHeight: Integer;
    //Calculates the visible coordinates of a single cell.
    function CellRect(ACol, ARow: Integer): TRect;
    //Calculates the visible coordinates of a rectangle of cells.
    function BoxRect(ALeft, ATop, ARight, ABottom: Integer): TRect;
    //Calculates the client rectangle of a rectangle of cells.
    procedure GridRectToClientRect(GridRect: TGMGridRect;
                                   var ClientRect: TRect;
                                   IncludeLine: Boolean);
    //Calculates the cell at the specified client coordinate.
    function CalcCellFromPoint(X, Y: Integer;
                               const DrawInfo: TGridDrawInfo): TGMGridCoord;
    //Calculates the information about the current view of the grid.
    procedure CalcDrawInfo(var DrawInfo: TGridDrawInfo);
    //Calculates and sets the information about the currently shown cells.
    procedure CalcDrawInfoXY(var DrawInfo: TGridDrawInfo;
                             UseWidth, UseHeight: Integer);
    //Calculates the information about the always visible parts of the grid.
    procedure CalcFixedInfo(var DrawInfo: TGridDrawInfo);
    //Calculates whether the size of a column can be changed at the position.
    procedure CalcSizingState(X, Y: Integer; var State: TGMGridState;
                              var Index: Integer;
                              var SizingOrgSize, SizingOfs: Integer;
                              const FixedInfo: TGridDrawInfo);
    //Calculates the minimum TopLeft that will put the given Coord in view.
    function CalcMinTopLeft(const Coord: TGMGridCoord;
                            const DrawInfo: TGridDrawInfo): TGMGridCoord;
    //Returns whether the grid is currently active, has the focus.
    function IsActiveControl: Boolean;


    //Cancels the current mode/state of the grid.
    procedure CancelMode;
    //Used during painting to temporarily change the orientation of the canvas.
    procedure ChangeGridOrientation(RightToLeftOrientation: Boolean);
    //Changes the number of columns and/or rows of the grid.
    procedure ChangeSize(NewColCount, NewRowCount: Integer);
    //Makes sure the specified coordinates are shown to the user.
    procedure ClampInView(const Coord: TGMGridCoord);
    //Moves the focus to the specified cell, maybe extending the selection.
    procedure FocusCell(ACol, ARow: Integer; MoveAnchor: Boolean);
    //Invalidates the rectangle of cells so they will be repainted shortly.
    procedure InvalidateRect(ARect: TGMGridRect);
    //Marks a single cell to be repainted.
    procedure InvalidateCell(ACol, ARow: Integer);

    //Marks a whole column to be repainted.
//    procedure InvalidateCol(ACol: Integer);

    //Marks a whole row to be repainted.
    procedure InvalidateRow(ARow: Integer);
    //Handles the scrolling of the grid using the valid 32-bit position.
    procedure ModifyScrollBarChecked(ScrollBar, ScrollCode, Pos: Cardinal;
                                     UseRightToLeft: Boolean);