نام (NAME)

FvwmForm - ماژول فرم ورودی برای Fvwm

خلاصه دستور (SYNOPSIS)

Module FvwmForm [ Alias ]

برنامهٔ FvwmForm باید توسط Fvwm اجرا (spawn) شود. اگر از خط فرمان فراخوانی گردد، FvwmForm شمارهٔ نسخهٔ خود را چاپ کرده و خارج می‌شود.

توضیحات (DESCRIPTION)

ماژول FvwmForm سازوکاری برای دریافت ورودی از کاربر و اقدام متناسب با آن فراهم می‌کند. این هدف با استفاده از فرمی محقق می‌شود که کاربر می‌تواند آن را پر کرده و از طریق آن، کارهایی را که می‌خواهد Fvwm انجام دهد انتخاب نماید. یک فرم شامل پنج نوع مؤلفه است: برچسب‌های متنی، ورودی‌های متنی تک‌خطی، گزینه‌های مانعة‌الجمع (انحصاری)، گزینه‌های چندانتخابی، و دکمه‌های کنش (action). این مؤلفه‌ها در چندین سطر و با چیدمانی بسیار منعطف مرتب می‌شوند.

یک برچسب متنی فقط برای ارائهٔ توضیحات به کار می‌رود و نمی‌تواند هیچ ورودی‌ای دریافت کند.

یک مدخل مهلت زمانی (timeout)، سازوکاری برای تعیین سرآمدن زمان فرم و اجرای یک کنش معین پس از اتمام مهلت فراهم می‌سازد. شمارش معکوس به صورتی مشابه با برچسب متنی نمایش داده می‌شود، با این تفاوت که بر اساس مدت‌زمان باقی‌مانده به‌روزرسانی می‌گردد.

از یک فیلد ورودی متن می‌توان برای ویرایش یک رشتهٔ متنی تک‌خطی استفاده کرد. FvwmForm کلیدهای جابه‌جایی نشانگر به سبک Emacs را می‌پذیرد. برای جزئیات بیشتر به FvwmFormInput مراجعه کنید. رونوشت با ماوس پشتیبانی نمی‌شود، اما می‌توانید جای‌گذاری (paste) کنید.

یک بخش انتخابی از چندین گزینه تشکیل می‌شود.

خود بخش انتخابی یک موجودیت منطقی است که هیچ ویژگی نمایشی و ظاهری ندارد.

هر گزینه به صورت یک دکمهٔ فشاری به همراه یک برچسب متنی توضیحی در ادامهٔ آن نمایش داده می‌شود. هنگام انتخاب، گزینهٔ مانعة‌الجمع دایره‌ای را در وسط نشان می‌دهد، در حالی که گزینهٔ چندگانه علامت تیک را به نمایش می‌گذارد.

یک دکمهٔ کنش، هنگامی که فعال شود یک یا چند دستور را به Fvwm ارسال کرده یا دستورهای پوسته را اجرا می‌کند. این دستورهای پوسته می‌توانند حاوی محتوای فیلدهای ورودی فرم بوده و وضعیت گزینه‌های تنظیم‌شده در فرم را منعکس کنند.

دکمه‌های کنش را می‌توان از طریق صفحه‌کلید یا ماوس فعال کرد.

مقداردهی اولیه (INITIALIZATION)

اگر FvwmForm بدون نام مستعار (alias) فراخوانی شود، از دستورهای پیکربندی که با "*FvwmForm" آغاز می‌شوند استفاده می‌کند.

معمولاً FvwmForm را با یک نام مستعار فراخوانی می‌کنید که بیانگر نام یک فرم، دستورهای پیکربندی و فایل پیکربندی آن است. برای نمونه، دستور "Module FvwmForm Rlogin" از دستورهای پیکربندی که با "*Rlogin" آغاز می‌شوند استفاده کرده و فایل پیکربندی اختیاری "Rlogin" را می‌خواند.

تمام فرم‌ها، صرف‌نظر از نام مستعار، ابتدا دستورهای پیکربندی‌ای را بررسی می‌کنند که با "*FvwmFormDefault" شروع می‌شوند. این دستورها معمولاً از فرم درونی "FvwmForm-Form" تأمین می‌شوند که دستورها را در فایل ".FvwmForm" ذخیره می‌کند.

خواندن فیزیکی فایل ورودی اختیاری ".FvwmForm" تنها در نخستین باری که FvwmForm فراخوانی می‌شود، یا پس از به‌روزرسانی فایل توسط "FvwmForm-Form" صورت می‌پذیرد.

هنگامی که فایل ".FvwmForm" خوانده می‌شود، این کار با ارسال دستور "Read .FvwmForm Quiet" به fvwm انجام می‌گیرد. به دلیل نحوهٔ کارکرد دستور "read"، این فایل می‌تواند در پوشهٔ کاربری شخصی fvwm شما و یا در پوشهٔ داده‌های fvwm قرار داشته باشد. برای اطلاعات بیشتر دربارهٔ متغیر محیطی $FVWM_USERDIR به توضیحات دستور read در صفحهٔ راهنمای fvwm مراجعه کنید.

سپس FvwmForm باقی‌ماندهٔ پیکربندی‌های ذخیره‌شده توسط fvwm را می‌خواند. fvwm پیکربندی‌ها را به طور پیوسته نگهداری می‌کند. پیکربندی اولیه از فایل .fvwm2rc می‌آید. منابع دیگر، از جمله دستورهای "Read" نیز می‌توانند یک فرم را تعریف کنند.

هنگام اجازه دادن به FvwmForm و fvwm برای خواندن فایل‌ها، به یاد داشته باشید که این فایل‌ها حاوی دستورهایی هستند که می‌توانند دستورهای پوسته را اجرا نمایند؛ بنابراین باید در تعیین دسترسی‌های این فایل‌ها دقت کافی به خرج دهید.

چنانچه FvwmForm با بافتار پنجره (window context) فراخوانی شود (برای نمونه از منوی یک پنجره)، تمام دستورهایی که به Fvwm ارسال می‌کند دارای همان بافتار پنجره خواهند بود. این امر به FvwmForm اجازه می‌دهد پنجره‌ای را که از آن فراخوانی شده است کنترل کند.

پس از خوانده شدن تمامی دستورهای پیکربندی، FvwmForm فرم تعریف‌شده توسط این دستورها را به نمایش می‌گذارد..SH "پیش‌فرض‌ها (DEFAULTS)"

برنامه FvwmForm یک فرم توکار به نام «FvwmForm-Form» ایجاد می‌کند که فایلی به نام «.FvwmForm» می‌سازد. این فایل شامل رنگ‌ها و قلم‌های پیش‌فرض ذخیره‌شده برای فرم است. فرم‌های دیگر از این پیش‌فرض‌ها استفاده می‌کنند، مگر اینکه درون خود فرم بازنویسی شده باشند.

فرم ایجادکننده پیش‌فرض‌ها معمولاً از یک «منوی ماژول» فراخوانی می‌شود. برای مثال، اگر نام منوی ماژول خود را «Module-Popup» بگذارید، این خط را اضافه خواهید کرد: AddToMenu "Module-Popup" "FvwmForm Defaults" FvwmForm FvwmForm-Form

هنگامی که «FvwmForm Defaults» را از منوی ماژول خود انتخاب می‌کنید، فرمی نمایش داده می‌شود که پیش‌فرض‌های فعلی را نشان داده و به شما اجازه تغییر آن‌ها را می‌دهد. اگر دکمه «Save Restart Me» را فعال کنید، فایل «.FvwmForm» نوشته شده و «FvwmForm-Form» خارج می‌شود و برای نمایش پیش‌فرض‌های جدید مجدداً راه‌اندازی می‌گردد.

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

# This file last created by FvwmForm-Form on Sun Nov 28 11:18:26 EST 1999.
*FvwmFormDefault: Font 10x20
*FvwmFormDefault: InputFont 8x13bold
*FvwmFormDefault: ButtonFont 10x20
*FvwmFormDefault: TimeoutFont 10x20
*FvwmFormDefault: Fore white
*FvwmFormDefault: Back cornflowerblue
*FvwmFormDefault: Colorset -1
*FvwmFormDefault: ItemFore green
*FvwmFormDefault: ItemBack gray40
*FvwmFormDefault: ItemColorset -1
*FvwmFormDefault: ButtonPointer hand2
*FvwmFormDefault: ButtonInPointer star
*FvwmFormDefault: InputPointer gumby
*FvwmFormDefault: ButtonPointerFore blue
*FvwmFormDefault: ButtonPointerBack gray
*FvwmFormDefault: ButtonInPointerFore gray
*FvwmFormDefault: ButtonInPointerBack blue
*FvwmFormDefault: InputPointerFore
*FvwmFormDefault: InputPointerBack

دستورات موجود در این فایل درست مانند هر دستور دیگر FvwmForm هستند، با این تفاوت که با «*FvwmFormDefault» آغاز می‌شوند.

برنامه FvwmForm فایل «.FvwmForm» را تنها بار اولی که اجرا می‌شود یا پس از تغییر فایل توسط «FvwmForm-Form» می‌خواند. این کار با ارسال دستور «*FvwmFormDefault: Read x» انجام می‌شود که در آن «x» برابر با «y» یا «n» قرار می‌گیرد. مقدار «n» باعث می‌شود FvwmForm دستور «read .FvwmForm quiet» را به fvwm ارسال کند.

جایگزینی متغیرها (VARIABLE SUBSTITUTION)

اگر متغیرها و مقادیر را در خط فرمانی که برای راه‌اندازی FvwmForm استفاده می‌شود ارائه دهید (مانند این):

Module FvwmForm MyForm ACTION=Browse "TITLE=Browse Form"

آنگاه همه دستورات ورودی FvwmForm تحت جایگزینی متغیر قرار می‌گیرند. متغیرها از خط فرمان صادر (export) می‌شوند. سپس هر دستور با استفاده از متغیرهای محیط گسترش می‌یابد. برای مثال، با فرض فراخوانی بالا برای «MyForm»، دستورات به این صورت تغییر خواهند کرد:

قبل: *MyForm: Text "$TITLE, Home $HOME, Going to $ACTION" بعد: *MyForm: TEXT "Browse Form, Home /home/me, Going to Browse"

استفاده از این قابلیت باید امکان استفاده از یک فرم را برای مجموعه‌های مختلفی از داده‌های ورودی فراهم سازد.

پیکربندی (CONFIGURATION)

دستورات زیر را می‌توان در فایل .fvwm2rc یا از طریق هر یک از روش‌های دیگری که fvwm دستورات را می‌پذیرد تنظیم کرد. ساده‌ترین شیوه، ایجاد فایلی در دایرکتوری داده‌های مستقل از معماریِ فقط‌خواندنی، [PREFIX/share/fvwm] یا دایرکتوری شخصی fvwm شما [$HOME/.fvwm] است که با نام مستعار فرم مطابقت داشته باشد.

در پاراگراف‌های زیر، رشته «FvwmForm» معمولاً همان نام مستعار فرم خواهد بود.

برنامه FvwmForm دستورات را هم پیش از نمایش فرم و هم در حین نمایش آن می‌خواند.

دستورات زیر پیش از نمایش فرم پذیرفته می‌شوند:

Back
Button
ButtonFont
ButtonInPointer
ButtonInPointerFore
ButtonInPointerBack
ButtonPointer
ButtonPointerFore
ButtonPointerBack
Choice
Command
Colorset
Font
Fore
GrabServer
Input
InputFont
InputPointer
ItemBack
ItemColorset
ItemFore
InputPointerFore
InputPointerBack
Line
Message
PadVText
Position
Selection
Separator
Text
Timeout
TimeoutFont
Title
UseData
WarpPointer

دستورات زیر در حین نمایش فرم پذیرفته می‌شوند:

Map
Stop
UnMap

امکانات «Map»، «UnMap» و «Stop» در حال توسعه هستند و در حال حاضر در این سند توضیح داده نشده‌اند، چرا که احتمال تغییر آن‌ها وجود دارد.

ترتیب گزینه‌ها اهمیت دارد. نخستین رنگ پس‌زمینه متن، «*FvwmFormBack»، که پیش از یک آیتم قابل نمایش قرار گیرد، رنگ پس‌زمینه پیش‌فرض را برای کل فرم تعیین می‌کند.

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

*FvwmForm: GrabServer

*FvwmForm: WarpPointer

*FvwmForm: Geometry geometry

*FvwmForm: Position x y

*FvwmForm: Colorset n

DestroyMenu Forms
AddToMenu Forms "&Q. QuitVerify" Module FvwmForm FvwmForm-QuitVerify
AddToMenu Forms "&C. Capture"    Module FvwmForm FvwmForm-Capture
AddToMenu Forms "&R. Rlogin"     Module FvwmForm FvwmForm-Rlogin
AddToMenu Forms "&T. Talk"       Module FvwmForm FvwmForm-Talk

مثال ۱ - تأیید خروج (EXAMPLE 1 - QUIT VERIFY)

این مثال روش mwm را برای تأیید خروج شبیه‌سازی می‌کند. کلید Return خروج را انجام می‌دهد و Escape خروج را لغو می‌کند. این فرم پس از ۲۰ ثانیه منقضی می‌شود و عملکردی معادل دکمهٔ 'Logout' را انجام می‌دهد.

DestroyModuleConfig  FvwmForm-QuitVerify: *
*FvwmForm-QuitVerify: GrabServer
*FvwmForm-QuitVerify: WarpPointer
*FvwmForm-QuitVerify: Command     Beep
*FvwmForm-QuitVerify: Line        center
*FvwmForm-QuitVerify: Text        "Do you really want to logout?"
*FvwmForm-QuitVerify: Line        expand
*FvwmForm-QuitVerify: Button      quit "Logout" ^M
*FvwmForm-QuitVerify: Command     Quit
*FvwmForm-QuitVerify: Button      restart   "Restart" ^R
*FvwmForm-QuitVerify: Command     Restart
*FvwmForm-QuitVerify: Button      quit "Cancel" ^[
*FvwmForm-QuitVerify: Command     Nop
*FvwmForm-QuitVerify: Timeout     200 Quit "Automatic logout will occur in %% tenth of seconds."

مثال ۲ - ورود از راه دور (EXAMPLE 2 - REMOTE LOGIN)

این مثال به کاربر اجازه می‌دهد نام میزبان و یک نام کاربری اختیاری را وارد کند و یک پنجرهٔ xterm را از میزبان راه دور باز می‌کند.

DestroyModuleConfig  FvwmForm-Rlogin: *
*FvwmForm-Rlogin: WarpPointer
*FvwmForm-Rlogin: Line         center
*FvwmForm-Rlogin: Text         "Login to Remote Host"
*FvwmForm-Rlogin: Line         center
*FvwmForm-Rlogin: Text         "Host:"
*FvwmForm-Rlogin: Input        HostName        20      ""
*FvwmForm-Rlogin: Line         center
*FvwmForm-Rlogin: Selection    UserSel single
*FvwmForm-Rlogin: Choice       Default Default on      "same user"
*FvwmForm-Rlogin: Choice       Custom  Custom  off     "user:"
*FvwmForm-Rlogin: Input        UserName        10      ""
*FvwmForm-Rlogin: Line         expand
*FvwmForm-Rlogin: Button       quit    "Login"         ^M
*FvwmForm-Rlogin: Command      Exec exec ssh $(Custom?-l $(UserName)) $(HostName) xterm -T x
term@$(HostName) -display $HOSTDISPLAY &
       # Before saving the data, remove any previously saved data:
       *FvwmForm-Rlogin: Command DestroyModuleConfig FvwmForm-RloginDefault: *
       # The "Login" button causes a login and a saving of the current data:
       *FvwmForm-Rlogin: Command !(                        /bin/echo \
         "# Created by FvwmForm-Rlogin on: `/bin/date`.";  /bin/echo \
         '*FvwmForm-RloginDefault: HostName $(HostName)';  /bin/echo \
         '*FvwmForm-RloginDefault: UserName $(UserName)';  /bin/echo \
         '*FvwmForm-RloginDefault: Default $(Default?on)'; /bin/echo \
         '*FvwmForm-RloginDefault: Custom $(Custom?on)' \
       ) > ${FVWM_USERDIR}/.FvwmForm-Rlogin
       *FvwmForm-Rlogin: Button       restart "Reset"
       *FvwmForm-Rlogin: Button       quit    "Cancel"        ^[
       *FvwmForm-Rlogin: Command      Nop
       # Tell FvwmForm to read vars from the .FvwmForm-RloginDefault file:
       *FvwmForm-Rlogin: UseData .FvwmForm-Rlogin *FvwmForm-RloginDefault

DestroyModuleConfig  FvwmForm-Capture: *
*FvwmForm-Capture: Line       center
*FvwmForm-Capture: Text       "Capture Window"
*FvwmForm-Capture: Line       left
*FvwmForm-Capture: Text       "File: "
*FvwmForm-Capture: Input      file            25      "/tmp/Capture"
*FvwmForm-Capture: Line       left
*FvwmForm-Capture: Text       "Printer: "
*FvwmForm-Capture: Input      printer         20      "$PRINTER"
*FvwmForm-Capture: Line       expand
*FvwmForm-Capture: Selection  PtrType single
*FvwmForm-Capture: Choice     PS      ps      on      "PostScript"
*FvwmForm-Capture: Choice     Ljet    ljet    off     "HP LaserJet"
*FvwmForm-Capture: Line       left
*FvwmForm-Capture: Text       "xwd options:"
*FvwmForm-Capture: Line       expand
*FvwmForm-Capture: Selection  Options multiple
*FvwmForm-Capture: Choice     Brd     -nobdrs off     "No border"
*FvwmForm-Capture: Choice     Frm     -frame  on      "With frame"
*FvwmForm-Capture: Choice     XYZ     -xy     off     "XY format"
*FvwmForm-Capture: Line       expand
*FvwmForm-Capture: Button     continue        "Capture"       ^M
*FvwmForm-Capture: Command    Exec exec xwd -out $(file) $(Options) &
*FvwmForm-Capture: Button     continue        "Preview"
*FvwmForm-Capture: Command    Exec exec xwud -in $(file) &
*FvwmForm-Capture: Button     continue        "Print"
*FvwmForm-Capture: Command    Exec exec xpr -device $(PtrType) $(file) | lpr -P $(printer) &
*FvwmForm-Capture: Button     quit            "Quit"

مثال ۴ - فرم گفتگو (EXAMPLE 4 - TALK FORM)

این مثال جایگزینی برای ماژول FvwmTalk فراهم می‌کند. ۲ فرم وجود دارد: «FvwmForm-Talk.» که دستورها را اجرا می‌کند یا آن‌ها را برای اجرا به fvwm ارسال می‌کند، و «FvwmForm-TalkHelp.» که یک فرم راهنما است.

در فرم راهنما، توجه کنید که چگونه فاصله‌گذاری عمودی خطوط تغییر یافته است. فاصله‌گذاری خطوط معمول FvwmForm فرض می‌کند که متن با دکمه‌ها درآمیخته است؛ فرم‌های راهنما به فاصله‌گذاری متفاوتی نیاز دارند.

# FvwmForm-Talk - Basic replacement for FvwmTalk
DestroyModuleConfig  FvwmForm-Talk: *
*FvwmForm-Talk: WarpPointer
# Layout
*FvwmForm-Talk: Line         center
*FvwmForm-Talk: Text         "Talk to Fvwm"
*FvwmForm-Talk: Line         left
*FvwmForm-Talk: Text         "Command:"
*FvwmForm-Talk: Input        Command 80 ""
*FvwmForm-Talk: Line         left
*FvwmForm-Talk: Text         "Msg:"
*FvwmForm-Talk: Message
*FvwmForm-Talk: Line         center
# Buttons
*FvwmForm-Talk: Button       restart    "Return - Execute"         ^M
*FvwmForm-Talk: Command        $(Command)
*FvwmForm-Talk: Button       continue    "F1 - Help" F1
*FvwmForm-Talk: Command        Module FvwmForm FvwmForm-TalkHelp
*FvwmForm-Talk: Button       restart     "F3 - Reset input" F3
*FvwmForm-Talk: Command        Nop
*FvwmForm-Talk: Button       quit        "F4 - Dismiss"  F4
*FvwmForm-Talk: Command        Nop

# FvwmForm-TalkHelp - Help Text for FvwmForm-Talk
DestroyModuleConfig  FvwmForm-TalkHelp: *
*FvwmForm-TalkHelp: WarpPointer
# Layout
*FvwmForm-TalkHelp: Line    center
*FvwmForm-TalkHelp: Text    "Talk to Fvwm - Help"
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    " "
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: PadVText 0
*FvwmForm-TalkHelp: Text    "Enter commands in the
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    "Commands beginning with
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    "shell as a sub-process of the form."
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    "All other commands are sent to fvwm for execution."
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    ""
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    "Fvwm error messages are shown on the
*FvwmForm-TalkHelp: Line    left
*FvwmForm-TalkHelp: Text    ""
# Buttons
*FvwmForm-TalkHelp: Line    center
*FvwmForm-TalkHelp: Button  quit    "Return - Dismiss"         ^M
*FvwmForm-TalkHelp: Command   Nop

کپی‌رایت (COPYRIGHTS)

برنامه FvwmForm اثر اصلی Thomas Zuwei Feng است ( <ztfeng@math.princeton.edu>).

کپی‌رایت فوریه ۱۹۹۵، Thomas Zuwei Feng. هیچ‌گونه تضمین یا گارانتی به هر نحو، صریح یا ضمنی ارائه نمی‌شود. از این برنامه با مسئولیت خود استفاده کنید. بدین‌وسیله مجوز استفاده، تغییر و بازتوزیع این برنامه داده می‌شود، به شرطی که این حق‌کپی‌رایت دست‌نخورده باقی بماند.

تغییرات (CHANGES)

در طول پاییز ۱۹۹۸، Dan Espen تمامی محدودیت‌های اندازه فرم را حذف کرد، امکان تغییر نامحدود فونت و رنگ، کنترل فاصله‌گذاری فرم، خواندن فایل پیکربندی، کنترل سراسری ظاهر، اجرای همگام دستورات، نمایش پیام‌های خطا، جایگزینی متغیرها، اشاره‌گرهای قابل‌پیکربندی و کلی خرابکاری دیگر را اضافه نمود. هیچ کپی‌رایت اضافی اعمال نمی‌شود.