'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMQUERY 1 "" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmconfirm\f1,
\f3pmmessage\f1,
\f3pmquery\f1 \- کادر محاوره‌ای چندمنظوره
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmconfirm\f1
[\f3\-c\f1]
[\f3\-b\f1 \f2button-name\f1]
[\f3\-B\f1 \f2default-button-name\f1]
[\f3\-t\f1 \f2string\f1]
[\f3\-file\f1 \f2filename\f1]
[\f3\-icon\f1 \f2icontype\f1]
[\f3\-font\f1 \f2font\f1]
[\f3\-header\f1 \f2titlebar-string\f1]
[\f3\-useslider\f1]
[\f3\-noslider\f1]
[\f3\-noframe\f1]
[\f3\-exclusive\f1]
.br
.PP
\f3pmmessage\f1
[\f3\-buttons\f1 \f2label1\f1[:\f2value1\f1][,\f2label2\f1[:\f2value2\f1][,...]]]
[\f3\-center\f1]
[\f3\-nearmouse\f1]
[\f3\-default\f1 \f2button\f1]
[\f3\-file\f1 \f2filename\f1]
[\f3\-print\f1]
[\f3\-timeout\f1 \f2sec\f1]
.I message...
.br
.PP
\f3pmquery\f1
[\f3\-input\f1]
[\f3all above options...\f1]
[\f2message...\f1]
.SH "توضیحات (DESCRIPTION)"
برنامهٔ
.B pmquery
یک پیاده‌سازی سازگار با گزینه‌های خط فرمان از ابزارهای
.B xconfirm
و
.B xmessage
را با ظاهر و رفتاری یکپارچه با
.B pmchart
ارائه می‌دهد.
به منظور بهبود کارایی اختصاصی آن‌ها برای
.BR pmchart ،
قابلیت‌های متعددی فراتر از ابزارهای اصلی اضافه شده است، اما تا جای ممکن رفتارهای اصلی حفظ شده‌اند.
.PP
ابزار
.B pmconfirm
به ازای هر گزینهٔ
.B \-t
مشخص‌شده یک خط متنی (یا در صورت استفاده از گزینهٔ
.BR \-file ،
یک فایل) و به ازای هر گزینهٔ
.B \-b
تعیین‌شده یک دکمه نمایش می‌دهد.
هنگامی که یکی از دکمه‌ها فشرده شود، برچسب آن دکمه در خروجی استاندارد
.B pmquery
نوشته می‌شود.
این سازوکار، روشی برای ارتباط یا دریافت بازخورد از درون اسکریپت‌های شل و ابزاری برای نمایش اطلاعات سودمند به کاربر از سوی یک برنامه فراهم می‌سازد.
.PP
ابزار
.B pmmessage
پنجره‌ای شامل پیامی از خط فرمان، یک فایل یا ورودی استاندارد را نمایش می‌دهد.
این ابزار افزون بر این امکان ارتباط دادن دکمه‌ها به یک وضعیت خروج را فراهم می‌کند، و تنها به‌صورت اختیاری برچسب دکمه را در خروجی استاندارد می‌نویسد.
.PP
ابزار
.B pmquery
ابزارهای یادشده را گسترش داده تا به‌صورت محدود از ورودی کاربر در قالب متن آزاد نیز پشتیبانی کند.
در این حالت
.BR \-input ،
با فشرده شدن دکمهٔ پیش‌فرض، هر متن واردشده در خروجی چاپ می‌شود.
یک متن پیش‌فرض نیز می‌تواند با استفاده از سازوکارهای مشابه دیگر ابزارها وارد شود.
.PP
گزینه‌های خط فرمان مختلفی برای تعیین سبک قلم، سبک قاب، حالت انحصاری (modality) و نمایش یکی از چندین آیکون گوناگون برای ارائهٔ بازخورد بصری متناسب به کاربر در دسترس هستند.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های موجود در خط فرمان عبارتند از:
.TP 5
.B \-c\f1, \f3\-center\f1
پنجره را در مرکز صفحه نمایش قرار می‌دهد.
.TP
.B \-nearmouse
پنجره را نزدیک مکان‌نمای ماوس باز می‌کند.
.TP
.B \-b \f2button-name\f1
دکمه‌ای با برچسب
.I button-name
نمایش می‌دهد.
اگر
.I button-name
یک رشتهٔ خالی باشد، دکمه در آن موقعیت نمایش داده نمی‌شود.
اگر هیچ گزینهٔ
.B \-b
ارائه نشود، پیش‌فرض دکمه‌ای با برچسب Continue خواهد بود.
وضعیت خروج مرتبط با
.I button-name
برابر با صفر است.
.TP
.B \-B \f2button-name\f1
دکمه‌ای با برچسب
.I button-name
نمایش می‌دهد و آن را به عنوان دکمه‌ای که هنگام فشردن Enter فعال می‌شود مشخص می‌سازد.
وضعیت خروج مرتبط با
.I button-name
برابر با صفر است.
.TP
.B \-buttons \f2button,button,.\|.\|.\f1
این گزینه به ازای هر
\f2button\f1
که با کاما جدا شده باشد، یک دکمه ایجاد می‌کند.
هر
\f2button\f1
شامل یک برچسب است که اختیاری می‌تواند یک دونقطه و یک مقدار وضعیت خروج به دنبال آن بیاید.
در صورت انتخاب آن دکمه، مقدار خروج بازگردانده خواهد شد.
مقدار خروج پیش‌فرض ۱۰۰ به علاوه شمارهٔ دکمه است.
شماره‌گذاری دکمه‌ها از سمت چپ و با عدد یک آغاز می‌شود.
.TP
.B \-default \fIlabel\fP
دکمه‌ای با برچسب منطبق با \fIlabel\fP را به عنوان دکمه پیش‌فرض تعیین می‌کند.
اگر مشخص نشود، هیچ دکمه پیش‌فرضی وجود نخواهد داشت.
ریسورس متناظر با آن \fBdefaultButton\fP است.
فشردن Return در هر کجای پنجرهٔ \fIxmessage\fP دکمه پیش‌فرض را فعال می‌کند.
دکمه پیش‌فرض دارای حاشیه‌ای پهن‌تر از سایر دکمه‌ها است.
.TP
.B \-t \f2message\f1
پیام را نمایش می‌دهد.
هر تعداد رشته را می‌توان در خط فرمان مشخص کرد (پیش از هر رشته باید گزینهٔ
.B \-t
بیاید).
.TP
.B \-file \f2filename\f1
فایل
.I filename
را نمایش می‌دهد.
تمام گزینه‌های
.B \-t
نادیده گرفته خواهند شد.
مقدار `\f2\-\f1' برای \f2filename\f1 محتوا را از ورودی استاندارد می‌خواند.
.TP
.B \-icon \f2icontype\f1
آیکون
.I icontype
را نمایش می‌دهد که در آن icontype یکی از موارد زیر است:
.IR info ،
.IR error ،
.IR question ،
.IR warning ،
.IR critical .
همچنین مقدار
.I action
برای سازگاری با نسخه‌های پیشین، به عنوان مترادفی برای
.I error
پذیرفته می‌شود.
ابزار
.B pmquery
علاوه بر انواع اصلی
.B xconfirm
که پیش‌تر ذکر شد، انواع آیکون
.I archive
و
.I host
را نیز پشتیبانی می‌کند.
.TP
.B \-font \f2fontname\f1
از fontname به عنوان قلم استفاده می‌کند.
این گزینه تنها هنگام استفاده از سامانه پنجره X (یا X Window System) در دسترس است.
.TP
.B \-header \f2string\f1
از string به عنوان عنوان پنجره استفاده می‌کند.
.TP
.B \-print
باعث می‌شود برنامه برچسب دکمه فشرده‌شده را در خروجی استاندارد بنویسد.
این رفتار، پیش‌فرض ابزارهای
.B pmconfirm
و
.B pmquery
است.
.TP
.B \-noprint
باعث می‌شود برنامه برچسب دکمه فشرده‌شده را در خروجی استاندارد ننویسد.
این رفتار، پیش‌فرض ابزار
.B pmmessage
است.
.TP
.B \-geometry \f2geometry-string\f1
یک رشتهٔ مشخصات ابعاد و موقعیت (geometry) سازگار با X را به ابزار ارائه می‌دهد.
این گزینه تنها هنگام استفاده از X Window System در دسترس است.
.TP
.B \-useslider
هنگام نمایش یک فایل، همواره از اسلایدر (نوار پیمایش) استفاده می‌کند و نیاز به آن را به‌صورت خودکار تشخیص نمی‌دهد.
.TP
.B \-noslider
هیچ اسلایدری ایجاد نمی‌کند و متن را به اندازهٔ پنجره برش می‌دهد، به جای این که نیاز به اسلایدر را خودکار بررسی کند.
.TP
.B \-noframe
هیچ قابی در اطراف محتویات نمایش نمی‌دهد.
.TP
.B \-exclusive
صفحه‌کلید و اشاره‌گر ماوس را در انحصار می‌گیرد (grab) و تا زمانی که دکمه‌ای فشرده نشود، اجازهٔ هیچ ورودی دیگری را نمی‌دهد.
.TP
.B \-timeout \f2secs\f1
اگر کاربر تا \fIsecs\fP ثانیه روی هیچ دکمه‌ای کلیک نکند، با وضعیت خروج ۰ خارج می‌شود.
ریسورس متناظر با آن \fBtimeout\fP است.
.TP
.B \-?\f1, \f3\-h\f1, \f3\-help\f1
پیام راهنمای نحوهٔ استفاده را نمایش می‌دهد و خارج می‌شود.
.SH "مثال‌ها (EXAMPLES)"
اسکریپت شل زیر پنجره‌ای با آیکون اطلاعاتی نمایش می‌دهد و از کاربر یک سؤال بله یا خیر می‌پرسد که گزینهٔ پیش‌فرض آن "Yes" است.
.PP
.nf
 #! /bin/sh
 case `pmquery \-t "Really power down?" \-b No \-B Yes \-icon question
 in
   Yes) shutdown;;
   No) ;;
 esac
.fi
.PP
مثال دوم، که نام یک میزبان را درخواست می‌کند و سپس یک ترمینال به همراه یک نشست ssh متصل به میزبان درخواستی باز می‌کند.
.PP
.nf
 #! /bin/sh
 host=`pmquery \-input \-icon host \-b Cancel \-B OK \\
               \-header "Remote Terminal \- Secure Shell"
 [ "$host" = "Cancel" \-o \-z "$host" ] && exit
 gnome-terminal \-e "ssh $host"
.fi
.SH "محیط (ENVIRONMENT)"
ابزار
.B pmquery
انتخابی عالی برای مقدار پارامتر پیکربندی
.B PCP_XCONFIRM_PROG
در Performance Co-Pilot است (برای جزئیات بیشتر به
.BR pcp.conf (5)
مراجعه کنید).
.PP
توجه داشته باشید که متغیر
.B PCP_XCONFIRM_PROG
به‌صورت خودکار در ابزارهایی مانند
.B pmchart
بر روی
.B pmquery
تنظیم خواهد شد، مگر اینکه
.B PCP_XCONFIRM_PROG
پیش‌تر در محیط تنظیم شده باشد.
.SH "وضعیت خروج (EXIT STATUS)"
در صورت شناسایی خطا،
.B pmquery
همیشه مقدار ۱ را بازمی‌گرداند؛ بنابراین این مقدار نباید به هیچ دکمه‌ای اختصاص داده شود.
در صورت موفقیت و مگر در حالتی که از گزینهٔ \f2\-buttons\f1 استفاده شده باشد، کد بازگشتی صفر خواهد بود.
.SH "همچنین ببینید (SEE ALSO)"
.BR pmchart (1)
و
.BR pcp.conf (5).

.\" control lines for scripts/man-spell
.\" +ok+ defaultButton esac fontname noprint pmquery's titlebar xmessage