5 авг. 2013 г.

Windows Ribbon Framework. Выполнение команд

Перевод. Оригинал Executing Commands

Windows Ribbon Framework предоставляет вам возможность обращаться к командам, созданным в Ribbon Designer, но не дает вам напрямую обращаться к элементам управления на "ленте". Во время выполнения программы вы можете изменять некоторые свойства команд: заголовок, изображения, доступна ли команда пользователю.

Свойство TUIRibbon.Commands обеспечивает доступ ко всем созданным командам. По фразой "ко всем созданным командам" я имею ввиду, что команда добавляется в эту коллекцию только тогда, когда фреймворк создал эту команду. Фреймворк же создает команду только при первом обращении к ней. Например, команды, видимые на "ленте", будут созданы сразу же после загрузки "ленты". Команды же, доступные через различные подменю, будут созданы, когда эти подменю будут впервые вызваны пользователем.

Классы команд


Все команды наследуют от абстрактного родительского класса TUICommand, обладающего следующими свойствами:

  • Tag: изменяемая метка команды. Аналогична свойству Tag у элементов управления в Delphi.
  • CommandId: числовой идентификатор команды. Вы можете назначить этот идентификатор с помощью Ribbon Designer или позволить сделать это Ribbon Compiler. Для каждой команды Ribbon Designer создает константу, которая записывается в pas-файл при сборке или предварительном просмотре "ленты".
  • Enabled: должна ли быть доступна команда.
  • Caption*: заголовок команды.
  • Keytip*: клавиша или сочетание клавиш, используемые для обращения к команде при нажатой клавише Alt.
  • Shortcut: клавиша или сочетание клавиш для вызова команды. Вы не можете указать значение этого свойства во время проектирования "ленты", но можете изменить его во время выполнения приложения.
  • TooltipTitle*: заголовок всплывающей подсказки.
  • TooltipDescription*: текст всплывающей подсказки.
  • LargeImage*: используемое в настоящий момент изображение для вывода кнопки / другого элемента управления большого размера.
  • SmallImage*: используемое в настоящий момент изображения для вывода кнопки / другого элемента управления малого размера.
  • LargeHighContrastImage*, SmallHighContrastImage*: аналогичные двум предыдущим свойствам, но содержат изображения, использующиеся при высококонтрастных темах Windows.
  • ActionLink: позволяет связать команду с объектом TAction (подробнее позже).

*. При создании команды эти свойства не инициализируются и содержат "пустые" значения, так как фреймворк не предоставляет такой информации. Однако вы можете изменять значения указанных свойств, и если хоть однажды вы сделали это, свойство будет уже содержать новое значение.

Свойства, содержащие изображения, имеют тип TUIImage. Этот класс позволяет загружать изображения из файлов BMP, PNG, а также из ресурсов. Мы рассмотрим его позже, когда будем обсуждать работу с галереями.

Каждая команда в приложении является наследником TUICommand.  Класс команды зависит от того, как команда используется "лентой" (используется ли в качестве кнопки, элемента управления шрифтом, "флажка"  и т.п.). Ниже приведены классы команд и соответствующие им элементы управления "ленты":

Класс командыЭлементы управления "ленты"
TUICommandGroup*Группы на вкладке
TUICommandActionКнопки и кнопка вызова справки
TUICommandCollectionГалереи, поля со списком и панель быстрого доступа
TUICommandDecimalСчетчики
TUICommandBooleanПереключатели и "флажки"
TUICommandAnchor*Меню приложения, разворачивающиеся кнопки, split-кнопки и вкладки
TUICommandContextКонтекстные группы вкладок
TUICommandFontУправление шрифтом
TUICommandColorAnchorЦветовые палитры
TUICommandRecentItemsСписок использованных документов в меню приложения

*. Отмеченные классы не имеют никаких дополнительных свойств и событий помимо тех, что описаны у родительского класса TUICommand.


Обращение к командам


Вы можете обращаться к командам по их идентификаторам. Ribbon Designer уже создал для нас pas-файл со значениями этих идентификаторов. Теперь нужно только добавить этот файл в наш проект. В приложении-примере TextPad мы должны добавить в проект файл "Ribbon\RibbonMarkup.pas". В этом модуле для каждой команды, созданной в Ribbon Designer, вы можете найти соответствующую константу. Например, модуль (частично) может выглядеть так:

unit RibbonMarkup;

// *****************************************************************************
// * This is an automatically generated source file for UI Element definition  *
// * resource symbols and values. Please do not modify manually.               *
// *****************************************************************************

interface

const
  CmdTabHome = 2;
  CmdGroupClipboard = 3;
  CmdPaste = 4;
  CmdPasteSpecial = 5;
  CmdPasteMore = 6;
  CmdCut = 7;
  CmdCopy = 8;

implementation

end.

Имя каждой константы совпадает с именем команды, созданной в Ribbon Designer, кроме тех случаев, когда вы сами указали имя константы (свойство Symbol Name команды). Добавьте RibbonMarkup в объявление uses основной формы приложения.

Самым безопасным способом доступа к командам и их инициализации является переопределение метода CommandCreated основной формы. Например, так вы можете обратиться к командам Cut (Вырезать), Copy (Копировать) и Paste (Вставить):

procedure TFormMain.CommandCreated(const Sender: TUIRibbon;
  const Command: TUICommand);
begin
  inherited;
  case Command.CommandId of
    CmdPaste:
      begin
        FCmdPaste := Command as TUICommandAction;
        FCmdPaste.OnExecute := PasteExecute;
      end;

    CmdPasteSpecial:
      begin
        FCmdPasteSpecial := Command as TUICommandAction;
        FCmdPasteSpecial.SetShortCut([ssCtrl, ssAlt], 'V');
        FCmdPasteSpecial.OnExecute := NotImplemented;
      end;

    CmdCut:
      begin
        FCmdCut := Command as TUICommandAction;
        FCmdCut.OnExecute := CutExecute;
      end;

    CmdCopy:
      begin
        FCmdCopy := Command as TUICommandAction;
        FCmdCopy.OnExecute := CopyExecute;
      end;
  end;
end;

В приведенном коде видно, что мы указали комбинацию клавиш Ctrl+Alt+V для команды Paste special (Специальная вставка). Мы не можем указывать "горячие" клавиши во время проектирования "ленты", но можем их назначить во время работы программы. Для этой цели можно использовать как свойство ShortCut, так и метод SetShortCut. Обратите внимание, что мы не назначили "горячие" клавиши для команд Cut (Вырезать), Copy (Копировать) и Paste (Вставить), так как элемент управления TRichEdit уже поддерживает необходимые комбинации клавиш.

Связываем команды с объектами TAction


Начиная с версии 1.1 в библиотеке появилась возможность связывания команд с объектами TAction. Для этого каждая команда имеет свойство ActionLink. Укажите в качестве значения свойства ActionLink.Action объект TAction как в ниже приведенном примере:

procedure TFormMain.CommandCreated(const Sender: TUIRibbon;
  const Command: TUICommand);
begin
  inherited;
  case Command.CommandId of
    CmdPaste:
      begin
        FCmdPaste := Command as TUICommandAction;
        FCmdPaste.ActionLink.Action := ActionPaste;
      end;

    CmdPasteSpecial:
      begin
        FCmdPasteSpecial := Command as TUICommandAction;
        FCmdPasteSpecial.SetShortCut([ssCtrl, ssAlt], 'V');
        FCmdPasteSpecial.ActionLink.Action := ActionNotImplemented;
      end;

    CmdCut:
      begin
        FCmdCut := Command as TUICommandAction;
        FCmdCut.ActionLink.Action := ActionCut;
      end;

    CmdCopy:
      begin
        FCmdCopy := Command as TUICommandAction;
        FCmdCopy.ActionLink.Action := ActionCopy;
      end;
  end;
end;

Теперь, когда запустится команда, возникнет и событие TAction.OnExecute. Таким образом вы можете использовать один обработчик и для "ленты", и для других элементов управления из VCL. Для закрепления посмотрите пример "Text Pad with Action List", входящий в состав библиотеки.

TUICommandAction


Так как команды Cut (Вырезать), Copy (Копировать) и Paste (Вставить) представлены на "ленте" в виде кнопок, то реализуются они как объекты типа TUICommandAction. Этот класс обладает свойством-событием OnExecute, которое возникает, когда пользователь кликнул по кнопке. Обработчик события OnExecute для команды Paste (Вставить) будет выглядеть так:

procedure TFormMain.PasteExecute(const Args: TUICommandActionEventArgs);
begin
  RichEdit.PasteFromClipboard;
end;

Этот пример предполагает, что у вас на форме имеется экземпляр класса TRichEdit, именуемый RichEdit. Вы должны указать его свойству Align значение alClient, чтобы он занял на форме все место, не занятое "лентой".

Каждому обработчику события в качестве параметра передается запись Args. Тип параметра зависит от типа команды, но запись всегда содержит поля:

  • Command: команда, которая вызвала событие (аналогична параметру Sender в типичном обработчике события в Delphi).
  • Verb: как должно выполняться действие:

    • cvExecute: выполнить команду;
    • cvPreview: просмотреть результат выполнения команды;
    • cvCancelPreview: отменить предварительный просмотр результатов команды и вернуться к состоянию до просмотра;

  • Properties: дополнительные свойства события. Потребуется вам только в особенных случаях.

Поле Verb чаще всего используется в случаях с галереями. Например, в Word 2010, когда вы удерживаете курсор "мыши" над элементом галереи, команда выполняется в режиме cvPreview. В этом случае демонстрируется, как будет выглядеть фрагмент документа, если бы этот элемент галереи был применен. Когда пользователь уберет указатель "мыши" с галереи, команда выполнится в режиме cvCancelPreview. Word вернется к тому виду документа, который был до того, как был выбран элемент галереи. Наконец, когда пользователь кликнет по элементу галереи, команда выполнится в режиме cvExecute, что приведет к изменению документа.

В большинстве случаев вас не должно волновать значение поля Verb, и вы можете реализовать обработчик только для cvExecute.

Кстати, если вы захотите, то можете использовать один обработчик для нескольких команд. В обработчике вам нужно будет определить команду или ее идентификатор и выполнить соответствующее действие. Например, вы можете реализовать один обработчик для команд Cut (Вырезать), Copy (Копировать) и Paste (Вставить):

procedure TFormMain.ClipboardExecute(const Args: TUICommandActionEventArgs);
begin
  case Args.Command.CommandId of
    CmdPaste: RichEdit.PasteFromClipboard;
    CmdCopy : RichEdit.CopyToClipboard;
    CmdCut  : RichEdit.CutToClipboard;
  end;
end;

В следующем разделе мы рассмотрим другие типы команд.

Далее: Другие типы команд

Комментариев нет:

Отправить комментарий

Примечание. Отправлять комментарии могут только участники этого блога.