Перевод. Оригинал Executing Commands
Свойство TUIRibbon.Commands обеспечивает доступ ко всем созданным командам. По фразой "ко всем созданным командам" я имею ввиду, что команда добавляется в эту коллекцию только тогда, когда фреймворк создал эту команду. Фреймворк же создает команду только при первом обращении к ней. Например, команды, видимые на "ленте", будут созданы сразу же после загрузки "ленты". Команды же, доступные через различные подменю, будут созданы, когда эти подменю будут впервые вызваны пользователем.
*. При создании команды эти свойства не инициализируются и содержат
"пустые" значения, так как фреймворк не предоставляет такой информации.
Однако вы можете изменять значения указанных свойств, и если хоть
однажды вы сделали это, свойство будет уже содержать новое значение.
Свойства, содержащие изображения, имеют тип TUIImage. Этот класс позволяет загружать изображения из файлов BMP, PNG, а также из ресурсов. Мы рассмотрим его позже, когда будем обсуждать работу с галереями.
Каждая команда в приложении является наследником TUICommand. Класс команды зависит от того, как команда используется "лентой" (используется ли в качестве кнопки, элемента управления шрифтом, "флажка" и т.п.). Ниже приведены классы команд и соответствующие им элементы управления "ленты":
*. Отмеченные классы не имеют никаких дополнительных свойств и событий помимо тех, что описаны у родительского класса TUICommand.
Вы можете обращаться к командам по их идентификаторам. Ribbon Designer уже создал для нас pas-файл со значениями этих идентификаторов. Теперь нужно только добавить этот файл в наш проект. В приложении-примере TextPad мы должны добавить в проект файл "Ribbon\RibbonMarkup.pas". В этом модуле для каждой команды, созданной в Ribbon Designer, вы можете найти соответствующую константу. Например, модуль (частично) может выглядеть так:
Имя каждой константы совпадает с именем команды, созданной в Ribbon Designer, кроме тех случаев, когда вы сами указали имя константы (свойство Symbol Name команды). Добавьте RibbonMarkup в объявление uses основной формы приложения.
Самым безопасным способом доступа к командам и их инициализации является переопределение метода CommandCreated основной формы. Например, так вы можете обратиться к командам Cut (Вырезать), Copy (Копировать) и Paste (Вставить):
В приведенном коде видно, что мы указали комбинацию клавиш Ctrl+Alt+V для команды Paste special (Специальная вставка). Мы не можем указывать "горячие" клавиши во время проектирования "ленты", но можем их назначить во время работы программы. Для этой цели можно использовать как свойство ShortCut, так и метод SetShortCut. Обратите внимание, что мы не назначили "горячие" клавиши для команд Cut (Вырезать), Copy (Копировать) и Paste (Вставить), так как элемент управления TRichEdit уже поддерживает необходимые комбинации клавиш.
Начиная с версии 1.1 в библиотеке появилась возможность связывания команд с объектами TAction. Для этого каждая команда имеет свойство ActionLink. Укажите в качестве значения свойства ActionLink.Action объект TAction как в ниже приведенном примере:
Теперь, когда запустится команда, возникнет и событие TAction.OnExecute. Таким образом вы можете использовать один обработчик и для "ленты", и для других элементов управления из VCL. Для закрепления посмотрите пример "Text Pad with Action List", входящий в состав библиотеки.
Так как команды Cut (Вырезать), Copy (Копировать) и Paste (Вставить) представлены на "ленте" в виде кнопок, то реализуются они как объекты типа TUICommandAction. Этот класс обладает свойством-событием OnExecute, которое возникает, когда пользователь кликнул по кнопке. Обработчик события OnExecute для команды Paste (Вставить) будет выглядеть так:
Этот пример предполагает, что у вас на форме имеется экземпляр класса TRichEdit, именуемый RichEdit. Вы должны указать его свойству Align значение alClient, чтобы он занял на форме все место, не занятое "лентой".
Каждому обработчику события в качестве параметра передается запись Args. Тип параметра зависит от типа команды, но запись всегда содержит поля:
Поле Verb чаще всего используется в случаях с галереями. Например, в Word 2010, когда вы удерживаете курсор "мыши" над элементом галереи, команда выполняется в режиме cvPreview. В этом случае демонстрируется, как будет выглядеть фрагмент документа, если бы этот элемент галереи был применен. Когда пользователь уберет указатель "мыши" с галереи, команда выполнится в режиме cvCancelPreview. Word вернется к тому виду документа, который был до того, как был выбран элемент галереи. Наконец, когда пользователь кликнет по элементу галереи, команда выполнится в режиме cvExecute, что приведет к изменению документа.
В большинстве случаев вас не должно волновать значение поля Verb, и вы можете реализовать обработчик только для cvExecute.
Кстати, если вы захотите, то можете использовать один обработчик для нескольких команд. В обработчике вам нужно будет определить команду или ее идентификатор и выполнить соответствующее действие. Например, вы можете реализовать один обработчик для команд Cut (Вырезать), Copy (Копировать) и Paste (Вставить):
В следующем разделе мы рассмотрим другие типы команд.
Далее: Другие типы команд
Windows Ribbon Framework предоставляет вам возможность обращаться к командам, созданным в Ribbon Designer, но не дает вам напрямую обращаться к элементам управления на "ленте". Во время выполнения программы вы можете изменять некоторые свойства команд: заголовок, изображения, доступна ли команда пользователю.
Классы команд
Все команды наследуют от абстрактного родительского класса 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;
В следующем разделе мы рассмотрим другие типы команд.
Далее: Другие типы команд
Комментариев нет:
Отправить комментарий
Примечание. Отправлять комментарии могут только участники этого блога.