Development/Tutorials/Using KActions (fa)

چگونه از KAction ها و XMLGUI استفاده کنیم

سری آموزشی	آموزش مقدماتی
پیش‌نیازها	آموزش ۲ - KXmlGuiWindow, آگاهی مقدماتی از XML
پس از این	آموزش ۴ - ذخیره و بازیابی
مطالعه‌ی بیشتر	None

چکیده

این آموزش به شناسایی مفهوم action می‌پردازد. Actionها ابزاری هستند که به وسیله‌ی آن‌ها به کاربر اجازه می‌دهید با برنامه‌تان ارتباط برقرار کند.

برای مثال، فرض کنید بخواهیم به کاربر برنامه‌ی آموزش ۲ اجازه دهیم کادر متن را پاک کند؛ با کلیک روی دکمه‌ای در نوار ابزار، از طریق انتخاب گزینه‌ای از منوی File، یا به وسیله‌ی یک میان‌بر صفحه‌کلیدی. همه‌ی این‌ها را می‌توان با تنها یک KAction انجام داد.

KAction

KAction شیئی است که همه‌ی اطلاعات یک action خاص را در بر دارد. اطلاعاتی هم‌چون آیکن و دکمه‌های میان‌بر آن action. action پیوندی به یک slot دارد. این slot کاری را که action انجام می‌دهد تعریف می‌کند.

کد منبع

main.cpp

```
#include <KApplication>
```
```
#include <KAboutData>
```
```
#include <KCmdLineArgs>
```
```
 
```
```
#include "mainwindow.h"
```
```
 
```
```
int main (int argc, char *argv[])
```
```
{
```

  KAboutData aboutData( "tutorial3", "tutorial3",

```
      ki18n("Tutorial 3"), "1.0",
```

      ki18n("A simple text area using KAction etc."),

```
      KAboutData::License_GPL,
```

      ki18n("Copyright (c) 2007 Developer") );

  KCmdLineArgs::init( argc, argv, &aboutData );

```
  KApplication app;
```
```
 
```

  MainWindow* window = new MainWindow();

```
  window->show();
```
```
  return app.exec();
```
```
}
```

این‌بار تنها تغییرات جزئی در main.cpp داده شده؛ aboutData را تغییر کوچکی دادیم تا نشان دهد که این برنامه، مربوط به آموزش ۳ است.

mainwindow.h

```
#ifndef MAINWINDOW_H
```
```
#define MAINWINDOW_H
```
```
 
```
```
#include <KXmlGuiWindow>
```
```
#include <KTextEdit>
```
```
 
```
```
class MainWindow : public KXmlGuiWindow
```
```
{
```
```
  public:
```
```
    MainWindow(QWidget *parent=0);
```
```
 
```
```
  private:
```
```
    KTextEdit* textArea;
```
```
    void setupActions();
```
```
};
```
```
 
```
```
#endif
```

تنها یک تابع void setupActions() اضافه شده که همه‌ی کارهای آماده‌سازی KActionها را به عهده دارد.

mainwindow.cpp

```
#include "mainwindow.h"
```
```
 
```
```
#include <KApplication>
```
```
#include <KAction>
```
```
#include <KLocale>
```
```
#include <KActionCollection>
```
```
#include <KStandardAction>
```
```
 
```
```
MainWindow::MainWindow(QWidget *parent)
```
```
    : KXmlGuiWindow(parent)
```
```
{
```
```
  textArea = new KTextEdit;
```
```
  setCentralWidget(textArea);
```
```
 
```
```
  setupActions();
```
```
}
```
```
 
```
```
void MainWindow::setupActions()
```
```
{
```

  KAction* clearAction = new KAction(this);

```
  clearAction->setText(i18n("Clear"));
```

  clearAction->setIcon(KIcon("document-new"));

  clearAction->setShortcut(Qt::CTRL + Qt::Key_W);

  actionCollection()->addAction("clear", clearAction);

  connect(clearAction, SIGNAL(triggered(bool)),

```
          textArea, SLOT(clear()));
```
```
 
```

  KStandardAction::quit(kapp, SLOT(quit()),

                        actionCollection());

```
 
```
```
  setupGUI();
```
```
}
```

شرح

این برنامه بر پایه‌ی کد برنامه‌ی پیش یعنی KXmlGuiWindow در آموزش ۲ ساخته می‌شود. بیشترین تغییرات در mainwindow.cpp دیده می‌شود؛ یک تغییر ساختاری مهم. تابع سازنده‌ی MainWindow اکنون به جای setupGUI()، setupActions()</tt را صدا می‌زند. در <tt>setupActions()، ابتدا کد KAction جدید قرار می‌گیرد و سپس setupGUI() فراخوانی می‌شود.

ساختن شیء KAction

KAction در چند گام ساخته می‌شود. اولین گام include کردن سرایند KAction است و سپس ساختن شیء KAction:

#include <KAction>
...
KAction* clearAction = new KAction(this);

این کد، یک KAction به نام clearAction جدید می‌سازد.

تنظیم خصوصیات KAction

نوشته

حالا که شیء KAction خود را ساختیم، شروع می‌کنیم به تنظیم خصوصیات آن. نوشته‌ای که در منو و هم‌چنین زیر آیکن KAction در نوارابزار دیده خواهد شد را دستور زیر تنظیم می‌کند:

clearAction->setText(i18n("Clear"));

باز هم توجه داشته باشید که تمام نوشته‌ها از طریق تابع ()i18n رد می‌شوند. این کار برای این لازم است که رابط کاربر برنامه را بتوان به زبان دیگری برگرداند. (برای آگاهی بیشتر درباره‌ی بومی‌سازی برنامه می‌توانید آموزش بومی‌سازی را ببینید.)

آیکن

اگر قرار است action در یک نوار ابزار نمایش داده شود، بهتر است آیکنی همراه آن باشد تا کاری را که انجام می‌دهد به تصویر بکشد. دستور زیر با استفاده از تابع setIcon()، آیکن document-new از مجموعه آیکن‌های استاندارد KDE را برای clearAction قرار می‌دهد.

clearAction->setIcon(KIcon("document-new"));

کلید میان‌بر

تنظیم یک میان‌بر صفحه‌کلیدی برای انجام کار مورد نظرمان نیز به همان سادگی است:

clearAction->setShortcut(Qt::CTRL + Qt::Key_W);

این کد، Ctrl+W را به عنوان کلید میان‌بر clearAction تنظیم می‌کند.

افزودن به مجموعه

برای این که یک action برای XMLGUI Framework (که بعدا به تفصیل شرح داده می‌شود) قابل دسترسی باشد، باید به مجموعه action برنامه افزوده شود. مجموعه action را می‌توان با تابع actionCollection() به کار گرفت. مانند زیر:

actionCollection()->addAction("clear", clearAction);

در اینجا، clearAction به مجموعه افزوده شده و clear نام می‌گیرد. این نام (clear) توسط XMLGUI Framework برای ارجاع به این action استفاده می‌شود.

پیوندزدن action

اکنون action ما کاملا تنظیم شده، اما هنوز کاری انجام نمی‌دهد. پس لازم است به چیزی مفید پیوند داده شود. در این مثال (چون می‌خواهیم کادر متن پاک شود)، actionمان را به تابع clear() متعلق به KTextEdit پیوند می‌دهیم. این تابع، به وضوح کادر متن KTextEdit را پاک خواهد کرد.

connect( clearAction, SIGNAL( triggered(bool) ), 
         textArea, SLOT( clear() ) );

دقیقا مشابه همان کاری است که در Qt با یک QAction انجام می‌شود.

KStandardAction

برای actionهایی مانند 'quit'، 'save' و 'load' که تقریبا در هر برنامه‌ای انتظار وجودشان می‌رود، KActionهای پیش‌ساخته‌ی مناسبی وجود دارند که می‌توان از طریق KStandardAction به آن‌ها دست یافت.

استفاده از آن‌ها بسیار آسان است. پس از آن‌که سرایند را include کردید (#include <KStandardAction>)، تنها کافی است معین کنید چه کاری می‌خواهید انجام دهد و هم‌چنین به کدام KActionCollection اضافه شود. برای مثال:

KStandardAction::quit(kapp, SLOT(quit()), actionCollection());

این دستور یک KAction با آیکن، نوشته و میان‌بر مناسب می‌سازد و حتی آن را به منوی File اضافه می‌کند.

افزودن action به منوها و نوارهای ابزار

تا حالا، action جدید ما، "Clear" ساخته شده، اما هنوز به هیچ منو یا نوار ابزاری اضافه نشده است. این کار با تکنولوژی KDE به نام XMLGUI انجام خواهد شد. این تکنولوژی کارهای جالبی همچون ساختن نوارابزارهای متحرک انجام می‌دهد.

Note
در نسخه‌های آینده‌ی KDE، ممکن است XMLGUI جای خود را به یک فریم‌ورک جدید به نام liveui بدهد. در حال حاضر، XMLGUI تنها راه صحیح ساختن رابط کاربر برنامه‌های KDE است.

XMLGUI

تابع setupGUI() در KXmlGuiWindow برای ساخت GUI به سیستم XMLGUI وابسته است. XMLGUI این کار را با پردازش فایل XML حاوی توصیف رابط کاربر انجام می‌دهد.

قاعده‌ی نام‌گذاری این فایل XML به صورت appnameui.rc است که در آن appname نامی است که در KAboutData مشخص می‌کنید (در این‌جا tutorial3). بنابراین در مثال ما، این فایل tutorial3ui.rc نامیده می‌شود و در مسیر ساخت برنامه قرار می‌گیرد. این که این فایل نهایتا در کجا قرار می‌گیرد را CMake کنترل می‌کند.

فایل appnameui.rc

از آن‌جایی که توصیف رابط کاربر با XML انجام می‌شود، باید از قواعد دقیق و سخت‌گیرانه‌ای پیروی کند. در این‌جا قصد نداریم وارد عمق این مطلب شویم. برای اطلاعات بیش detailed XMLGUI page را ببینید.

tutorial3ui.rc

```
<?xml version="1.0" encoding="UTF-8"?>
```
```
<gui name="tutorial3"
```
```
     version="1"
```

     xmlns="http://www.kde.org/standards/kxmlgui/1.0"

     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

     xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0

                         http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

```
 
```
```
  <MenuBar>
```
```
    <Menu name="file" >
```
```
      <Action name="clear" />
```
```
    </Menu>
```
```
  </MenuBar>
```
```
 
```
```
  <ToolBar name="mainToolBar" >
```
```
    <text>Main Toolbar</text>
```
```
    <Action name="clear" />
```
```
  </ToolBar>
```
```
 
```
```
</gui>
```

تگ <Toolbar> به شما اجازه می‌دهد یک نوار ابزار توصیف کنید. نوار ابزار، نوار افقی بالای پنجره است که معمولا چند آیکن در آن دیده می‌شود. در این‌جا به آن نام یک‌تای mainToolBar داده شوده و هم‌چنین با استفاده از تگ <text> نوشته‌ی روی آن نیز Main Toolbar تنظیم شده است. clearAction با استفاده از تگ <Action> به نوار ابزار افزوده خواهد شد. پارامتر name در این تگ، رشته‌ای است که در mainwindow.cpp با addAction() به KActionCollection رد شده بود.

علاوه‌بر داشتن action در نوار ابزار، می‌توانیم آن را به منوها نیز اضافه کنیم. در این‌جا action ما به منوی File در تگ MenuBar اضافه می‌شود؛ درست به همان شیوه‌ای که آن را به نوار ابزار افزودیم.

اگر فایل rc. را از آخرین زمان کامپایل و نصب تغییر داده‌اید، پارامتر version در تگ <gui> را تغییر دهید تا سیستم مجبور به به‌روزرسانی فایل‌های cache خود شود.

توضیحاتی درباره‌ی تعامل میان کد و فایل rc.: منوها به طور خودکار به نمایش در می‌آیند. هر منو باید یک تگ فرزند <text/> داشته باشد، مگر زمانی که به منوهای استاندارد اشاره می‌کنند. actionها را باید دستی ساخت و با نامی که در فایل rc. مشخص می‌شود، به ()actionCollection اضافه کرد. هم‌چنین actionها می‌توانند غیرفعال یا پنهان شوند، اما منوها نمی‌توانند.

CMake

در پایان، فایل tutorial3ui.rc باید جایی قرار گیرد که KDE بتواند پیدایش کند (نمی‌توانیم آن را در شاخه‌ی سورس‌ها به خود رها کنیم!). این یعنی پروژه باید جایی نصب شود.

CMakeLists.txt

```
project(tutorial3)
```
```
 
```
```
find_package(KDE4 REQUIRED)
```
```
include_directories(${KDE4_INCLUDES})
```
```
 
```
```
set(tutorial3_SRCS 
```
```
  main.cpp
```
```
  mainwindow.cpp
```
```
)
```
```
 
```

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

```
 
```

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

```
 
```

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})

```
install(FILES tutorial3ui.rc 
```

        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)

این فایل تقریبا با هم‌سانش برای tutorial2 یکی است، ولی با دو خط اضافی در انتهای فایل که مشخص می‌کنند فایل‌ها باید کجا نصب شوند. اول tutorial3 در مسیر BIN_INSTALL_DIR نصب می‌شود، سپس فایل tutorial3ui.rc که ساختار رابط کاربر را توصیف می‌کند، در شاخه‌ی داده‌های برنامه نصب می‌شود.

ساخت، نصب و اجرا

اگر دسترسی نوشتن به شاخه‌ی نصب KDE4 خود ندارید، می‌توانید برنامه را در شاخه‌ی Home خود نصب کنید.

برای این‌که به CMake بگویید می‌خواهید برنامه را کجا نصب کنید، از سوییچ استفاده کنید. شما احتمالا می‌خواهید در یک مکان محلی برنامه‌تان را برای آزمایش نصب کنید (ممکن است کمی به نظر احمقانه برسد که این آموزش‌ها را در مسیر KDEتان نصب کنید!)، بنابراین دستورات زیر ممکن است مناسب باشند:

 mkdir build && cd build
 cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
 make install
 $HOME/bin/tutorial3

با این دستورات، یک ساختار شاخه‌بندی همانند شاخه‌های KDE در شاخه‌ی Home شما ساخته می‌شود و فایل اجرایی برنامه در $HOME/bin/tutorial3 قابل دسترسی خواهد بود.

به پیش

حالا می‌توانید به سوی ذخیره و بازیابی پیش بروید.