WML(5) File Formats Manual WML(5)

WML - قالب فایل فرا-زبان ویجت (widget meta-language) برای ایجاد کامپایلرهای uil

امکان فرا-زبان ویجت (WML) برای تولید مؤلفه‌های کامپایلر زبان واسط کاربر (UIL) استفاده می‌شود که بسته به مجموعه ویجت‌ها می‌توانند تغییر کنند. با استفاده از WML می‌توانید در UIL، پشتیبانی از ویجت‌های جدید را به مجموعه ویجت Motif یا برای یک مجموعه ویجت کاملاً تازه اضافه کنید.

فایل‌های WML پرونده‌های متنی ASCII هستند که می‌توانید با هر ویرایشگر متن استانداردی آن‌ها را ویرایش کنید. این فایل‌ها در دایرکتوری tools/wml توسط WML مورد دسترسی قرار می‌گیرند. طبق قرارداد، فایل‌های WML دارای پسوند .wml هستند. مجموعه ویجت Motif در فایل motif.wml توصیف شده است. این فایل همچنین فایل WML پیش‌فرض هنگام استفاده از ابزار WML است.

هنگام افزودن ویجت‌های جدید یا تغییر مشخصات ویجت‌ها، باید با یک نسخه رونوشت از فایل motif.wml شروع کنید. اگر در حال ساخت مجموعه ویجت جدیدی برای استفاده با UIL هستید، باید از صفر شروع کنید. در هر دو صورت، فایل motif.wml نمونه خوبی از نحو WML است و باید پیش از نوشتن فایل WML اختصاصی خود، با آن آشنا شوید.

فایل‌های WML دارای نحوی ساده، و در ساختار شبیه به UIL هستند. این نحو از عناصر زیر تشکیل شده است:

•
کامنت‌ها (Comments)
•
تعاریف نوع داده (Data Type Definitions)
•
تعاریف مجموعه کاراکتر (Character Set Definitions)
•
تعاریف مجموعه شمارشی (Enumeration Set Definitions)
•
تعاریف فهرست کنترل (Control List Definitions)
•
تعاریف کلاس (Class Definitions)
•
تعاریف فرزند (Child Definitions)
•
تعاریف منبع (Resource Definitions)

می‌توانید در هر کجای نحو از فاصله، تب یا خطوط جدید استفاده کنید، تا زمانی که کلمات کلیدی یا رشته‌ها را چندپاره نکنید، به‌جز اینکه کامنت‌ها در انتهای خط پایان می‌یابند. ترتیب عناصر برای نحو اهمیتی ندارد.

این توضیحات از قراردادهای تکمیلی زیر برای شرح نحو فرا-زبان ویجت استفاده می‌کند:

[  ]
نشان‌دهنده عناصر اختیاری است.
...
نشان می‌دهد که یک عنصر نحوی می‌تواند تکرار شود.
|
نشان‌دهنده انتخاب بین چندین مورد است.

می‌توانید در فایل WML کامنت قرار دهید. کامنت‌ها نحو زیر را دارند:

[any.element]!any.comment

کامنت‌ها با یک علامت تعجب شروع می‌شوند و تا انتهای خط ادامه می‌یابند. یک کامنت می‌تواند در یک خط مستقل شروع شود یا به دنبال هر بخشی از یک عنصر دیگر بیاید. کامنت معنای هیچ عنصر دیگری را تغییر نمی‌دهد. به عنوان مثال:

!This is a comment
!  that spans two lines.
DataType    !This is a comment following code.

تعاریف نوع داده تمام انواع داده منابع استفاده‌شده در فایل را ثبت می‌کنند. شما باید تمام انواع داده به کار رفته در فایل WML خود را ثبت کنید. تعاریف نوع داده دارای نحو زیر هستند:

DataType
     any.datatype [{ InternalLiteral = internal.name |
          DocName = "string"; [...]}];
     [...]

یک تعریف نوع داده با کلمه کلیدی DataType آغاز می‌شود. به دنبال کلمه کلیدی DataType فهرستی از انواع داده قرار می‌گیرد که می‌توانند با موارد زیر بیشتر اصلاح و مشخص شوند:

این مقدار، مقدار تعریف لیترال جدول نمادهای داخلی نام نوع داده را تعیین و تحمیل می‌کند. این اصلاح‌کننده تنها برای دور زدن تعاریف جدول نمادها که در کامپایلر UIL به‌صورت کد ثابت (hard-coded) تعریف شده‌اند به کار می‌رود. به‌ندرت باید از آن استفاده کرد.
یک رشته دلخواه برای استفاده در مستندات مشخص می‌کند. این رشته برای ارائه نامی متفاوت برای نوع داده جهت استفاده در مستندات، یا یک نام واحد برای نوع داده در صورتی که نوع داده دارای نام‌های مستعار باشد، در نظر گرفته شده است.

به عنوان مثال:

DataType OddNumber {DocName="OddNumber";};
         NewString;

تعاریف مجموعه کاراکتر، نام جعبه‌ابزار Motif و سایر اطلاعات مربوط به نام‌های مجموعه کاراکتر مورد استفاده در UIL را ثبت می‌کنند. تعاریف مجموعه کاراکتر دارای نحو زیر هستند:

CharacterSet
     any.character.set
          { [ FontListElementTag | XmStringCharsetName ] = "string";
               [ Alias = "string" ...; |
               Direction = [ LeftToRight | RightToLeft ]; |
               ParseDirection = [ LeftToRight | RightToLeft ]; |
               CharacterSize = [ OneByte | TwoByte ]; ]
               [ ... ] };
     [ ... ]

یک تعریف مجموعه کاراکتر با کلمه کلیدی CharacterSet شروع می‌شود. به دنبال کلمه کلیدی CharacterSet فهرستی از مجموعه‌های کاراکتر می‌آید که می‌توانند با موارد زیر تغییر یابند:

نام مجموعه کاراکتر را مشخص می‌کند، که به مؤلفه مجموعه کاراکتر یک بخش رشته مرکب (compound string segment) ایجادشده با این مجموعه کاراکتر تبدیل خواهد شد. این اصلاح‌کننده الزامی است.
یک یا چند نام مستعار برای نام مجموعه کاراکتر تعیین می‌کند. هر نام مستعار را می‌توان در UIL برای اشاره به همان مجموعه کاراکتر به کار برد.
جهت یک بخش رشته مرکب ایجادشده با این مجموعه کاراکتر را تعیین می‌کند. پیش‌فرض LeftToRight است.
جهتی را که رشته ورودی هنگام ایجاد یک بخش رشته مرکب با این مجموعه کاراکتر تجزیه می‌شود تعیین می‌کند. پیش‌فرض همان مقداری است که در Direction مشخص شده است.
تعداد بایت‌های هر کاراکتر در یک بخش رشته مرکب ایجادشده با این مجموعه کاراکتر را مشخص می‌کند. پیش‌فرض OneByte است.

به عنوان مثال:

CharacterSet
  iso_latin1
    { XmStringCharsetName = "ISO8859-1";
      Alias = "ISOLatin1"; };
  iso_hebrew_lr
    { XmStringCharsetName = "ISO8859-8";
      Alias = "iso_latin8_lr";
      Direction = RightToLeft;
      ParseDirection = LeftToRight; };
  ksc_korean
    { XmStringCharsetName = "KSC5601.1987-0";
      CharacterSize = TwoByte; };

تعاریف مجموعه شمارشی ثوابت نام‌گذاری‌شده‌ای را که در جعبه‌ابزار Motif برای مشخص کردن مقادیر برخی منابع به کار می‌روند، ثبت می‌کنند. تعاریف مجموعه شمارشی دارای نحو زیر هستند:

EnumerationSet
     resource.name: resource.type
          { enum.value.name; [ ... ] };

یک تعریف مجموعه شمارشی با کلمه کلیدی EnumerationSet آغاز می‌شود. برای هر مجموعه شمارشی تعریف‌شده، نام و نوع منبع فهرست می‌شود. نام منبع همان نام منبع جعبه‌ابزار Motif است که پیشوند XmN از ابتدای آن حذف شده و حرف اول آن بزرگ نوشته می‌شود. به عنوان مثال، نام منبع جعبه‌ابزار Motif برای XmNrowColumnType برابر RowColumnType است. نوع منبع، نوع داده برای آن منبع است؛ برای بیشتر منابع، این نوع integer است. به دنبال نام و نوع منبع، فهرستی از نام‌های مقادیر شمارشی می‌آید که می‌توانند به عنوان تنظیمات منبع استفاده شوند. این نام‌ها دقیقاً همان نام‌های موجود در جعبه‌ابزار Motif هستند.

به عنوان مثال:

EnumerationSet
  RowColumnType: integer
    { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;
      XmMENU_PULLDOWN; XmMENU_OPTION; };

مجموعه‌های شمارشی همچنین از مقادیر بولی (Boolean) پشتیبانی می‌کنند.

تعاریف فهرست کنترل نامی را به گروه‌هایی از کنترل‌ها اختصاص می‌دهند. می‌توانید بعداً از این فهرست‌های کنترل در تعاریف کلاس برای ساده‌سازی ساختار فایل WML خود استفاده کنید. تعاریف فهرست کنترل دارای نحو زیر هستند:

ControlList
     any.control.list [{ any.control; [...]}];

یک تعریف فهرست کنترل با کلمه کلیدی ControlList شروع می‌شود. پس از کلمه کلیدی ControlList هر تعداد تعریف فهرست کنترل می‌تواند بیاید. تعاریف فهرست کنترل از نام فهرست کنترل و به دنبال آن مجموعه‌ای از کنترل‌هایی که نشان می‌دهد تشکیل شده‌اند. به عنوان مثال:

ControlList
        Buttons {PushButton;
                 RadioButton;
                 CascadeButton;
                 NewCascadebutton;};

هر کنترل مشخص‌شده در فهرست کنترل باید به عنوان یک کلاس در فایل تعریف شده باشد.

تعاریف کلاس یک کلاس ویجت خاص را شامل جایگاه آن در سلسله‌مراتب کلاس، تابع کمکی (convenience function) جعبه‌ابزار، منابع و کنترل‌های آن شرح می‌دهند. باید برای هر ویجت یا گجت در مجموعه ویجت که می‌خواهید در UIL پشتیبانی شود، یک تعریف کلاس وجود داشته باشد. تعاریف کلاس دارای نحو زیر هستند:

Class class.name: MetaClass | Widget | Gadget
     [{[
     SuperClass = class.name; |
     ParentClass = parent.class.name; |
     InternalLiteral = internal.name; |
     Alias = alias; |
     ConvenienceFunction = convenience.function; |
     WidgetClass = widget.class; |
     DocName = "string"; |
     DialogClass = True | False; |
     Resources { any.resource.name [{
               Default = new.default.value; |
               Exclude = True |
               False;
               [...]} ];
          [...]}; |
     Controls { any.control.name; [...]};
     Children { any.child.name; [...] };
     [...]
     ]}];

تعاریف کلاس با کلمه کلیدی Class شروع می‌شوند. برای هر کلاس تعریف‌شده، نام کلاس و اینکه آیا کلاس یک فراکلاس (metaclass)، ویجت (widget) یا گجت (gadget) است فهرست می‌گردد. هر تعریف کلاس می‌تواند با کلمات کلیدی شرح داده شده در فهرست زیر بیشتر سفارشی‌سازی شود.

نام کلاس والد (ابرکلاس) را مشخص می‌کند. تنها ریشه سلسله‌مراتب کلاس‌ها فاقد SuperClass است.
نام کلاس والد ایجادشده خودکار ویجت را در صورت وجود مشخص می‌کند. این ویژگی امکان می‌دهد منابع مربوط به آن کلاسِ خودکار ایجادشده در نمونه‌های این کلاس استفاده شوند. به عنوان مثال، XmBulletinBoardDialog هم یک XmBulletinBoard و هم یک XmDialogShell ایجاد می‌کند. برای دسترسی به منابع کلاس والد XmDialogShell باید در اینجا مشخص گردد.
مقدار تعریف لیترال جدول نمادهای داخلیِ نام کلاس را تعیین و تحمیل می‌کند. این اصلاح‌کننده تنها برای دور زدن تعاریف جدول نمادها که در کامپایلر UIL به‌صورت کد ثابت قرار دارند استفاده می‌شود. به‌ندرت باید استفاده شود.
نام‌های جایگزین و مستعار کلاس را برای استفاده در مشخصات UIL تعیین می‌کند.
نام تابع کمکی ساخت (creation convenience function) را برای این کلاس مشخص می‌کند. تمام کلاس‌های ویجت و گجت باید دارای یک ConvenienceFunction باشند.
کلاس ویجت مرتبط با کلاس‌های نوع گجت را مشخص می‌کند. در حال حاضر، هیچ عملیاتی با این مقدار انجام نمی‌شود.
یک رشته دلخواه برای استفاده در مستندات تعریف می‌کند. در حال حاضر، هیچ عملیاتی با این مقدار انجام نمی‌شود.
مشخص می‌کند که آیا این کلاس یک کلاس دیالوگ است یا خیر. در حال حاضر، هیچ عملیاتی با این مقدار انجام نمی‌شود.
منابع کلاس ویجت را فهرست می‌کند. این کلمه کلیدی می‌تواند با موارد زیر بیشتر اصلاح شود:
یک مقدار پیش‌فرض جدید برای این منبع تعیین می‌کند. مقادیر پیش‌فرض منابع معمولاً در تعریف منبع تنظیم می‌شوند. اگر مقدار پیش‌فرض یک منبع به ارث رسیده توسط کلاس تغییر کند، مقدار پیش‌فرض جدید باید در اینجا قید شود.
مشخص می‌کند که آیا یک منبع به ارث رسیده باید از فهرست منابع کلاس مستثنی و حذف شود یا خیر. پیش‌فرض Exclude برابر False است.
نام‌های فرزندان خودکار ایجادشده این کلاس را فهرست می‌کند تا بتوان در فایل UIL به آن فرزندان دسترسی داشت.
کنترل‌هایی را که کلاس ویجت مجاز می‌داند فهرست می‌کند. کنترل‌ها می‌توانند کلاس‌های دیگر یا یک فهرست کنترل از تعاریف فهرست کنترل باشند.

مثال زیر از نمونه‌های تعاریف نوع داده و تعاریف فهرست کنترلِ بالا استفاده می‌کند.

Class
     TopLevelWidget: MetaClass
          {
          Resources
               {
               XtbNfirstResource;
               XtbNsecondResource;
               };
          };
     NewWidget: Widget
          {
          SuperClass = TopLevelWidget;
          ConvenienceFunction =
              XtbCreateNewWidget;
          Resources
               {
               XtbNnewResource;
               XtbNfirstResource
                  {Default="XtbNEW_VALUE";};
               XtbNsecondResource
                  {Exclude=True;};
               };
          Controls
               {
               NewWidget;
               Buttons;
               };
          };

تعاریف فرزند کلاس‌های فرزندان خودکار ایجادشده را ثبت می‌کنند. فرزندان خودکار ایجادشده در جاهای دیگرِ یک فایل uil با استفاده از کلمه کلیدی Children درون یک تعریف کلاس ارجاع داده می‌شوند. تعاریف فرزند دارای نحو زیر هستند:

Child child.name : class.name; [...]

که در آن child.name نام فرزند خودکار ایجادشده و class.name نام کلاس آن فرزند است.

تعاریف منبع یک منبع خاص را شامل نوع و مقدار پیش‌فرض آن شرح می‌دهند. باید برای هر منبع جدیدی که در تعاریف کلاس به آن ارجاع داده شده، یک تعریف منبع وجود داشته باشد. تعاریف منبع دارای نحو زیر هستند:

Resource
     resource.name: Argument | Reason | Constraint | SubResource
          [{[
          Type = type;
          [ResourceLiteral = resource.literal; ]
          [InternalLiteral = internal.name; ]
          [Alias = alias; ]
          [Related = related; ]
          [Default = default; ]
          [DocName = doc.name; ]
          [...]}]
     [...]

تعاریف منبع با کلمه کلیدی Resource شروع می‌شوند. برای هر تعریف منبع، نام منبع و این که منبع یک آرگومان (Argument)، دلیل/فراخوان بازگشتی (Reason)، محدودیت (Constraint) یا زیرمنبع (SubResource) است، قید می‌شود.

یک منبع استاندارد را نشان می‌دهد.
یک منبع فراخوان بازگشتی (callback) را نشان می‌دهد.
یک منبع محدودیت (constraint) را نشان می‌دهد.
در حال حاضر، هیچ عملیاتی با این مقدار انجام نمی‌شود.

تعریف منبع می‌تواند با کلمات کلیدی زیر بیشتر اصلاح و تنظیم شود:

نوع داده منبع را مشخص می‌کند. این نوع باید در تعریف نوع داده فهرست شده باشد.
کلمه کلیدی مورد استفاده در فایل UIL برای ارجاع به منبع را مشخص می‌کند. در Motif، نام منبع همانند ResourceLiteral است.
مقدار تعریف لیترال جدول نمادهای داخلیِ نام منبع را تعیین و تحمیل می‌کند. این اصلاح‌کننده تنها برای دور زدن تعاریف جدول نمادها که به‌صورت کد ثابت در کامپایلر UIL قرار دارند به کار می‌رود. به‌ندرت باید استفاده شود.
نام‌های جایگزین برای منبع جهت استفاده در مشخصات UIL را تعیین می‌کند.
یک فیلد با کاربرد ویژه است که اجازه می‌دهد منابعی که به عنوان شمارنده برای منابع جاری عمل می‌کنند، به منبع مرتبط شوند. کامپایلر UIL به طور خودکار مقدار این منبع مرتبط را برابر با تعداد آیتم‌ها در نمونه کامپایل‌شده از نوع resource.name تنظیم می‌کند.
مقدار پیش‌فرض منبع را مشخص می‌کند.
یک رشته دلخواه برای استفاده در مستندات تعریف می‌کند. در حال حاضر، هیچ عملیاتی با این مقدار انجام نمی‌شود.

مثال زیر از نمونه‌های تعاریف نوع داده، تعاریف فهرست کنترل و تعاریف کلاس در بالا استفاده می‌کند.

Resource
     XtbNfirstResource: Argument
          { Type = OddNumber;
            Default = "XtbOLD_VALUE";};
     XtbNsecondResource: Argument
          { Type = NewString;
            Default = "XtbNEW_STRING"; };
     XtbNnewResource: Argument
          { Type = OddNumber;
            Default = "XtbODD_NUMBER"; };
OpenMotif فایل‌های پیکربندی