مصدر القائمة

الإعلانات

مصدر القائمة

 

 

مصدر القائمة يقوم بتعريف قائمة التطبيق (قائمة الخيارات، قائمة السياق، أو القائمة الفرعية) يمكن تضخيمها بواسطة مضخم القائمة MenuInflater.

للحصول على إرشادات في إستخدام القوائم، راجع دليل مطوري القوائم.

موقع الملف:

res/menu/filename.xml
يستخدم اسم الملف كمعرف للمصدر.

جمع أنواع بيانات المصادر:

تشير المصادر إلى مصدر قائمة أو (مصدر فئة فرعيه).

الإشارة للمصدر:

في ملف الجافا: R.menu.filename
في ملف XML:
package:]menu.filename]@

بناء الجملة:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@[+][package:]id/resource_name"
          android:title="string"
          android:titleCondensed="string"
          android:icon="@[package:]drawable/drawable_resource_name"
          android:onClick="method name"
          android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
          android:actionLayout="@[package:]layout/layout_resource_name"
          android:actionViewClass="class name"
          android:actionProviderClass="class name"
          android:alphabeticShortcut="string"
          android:alphabeticModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:numericShortcut="string"
          android:numericModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:checkable=["true" | "false"]
          android:visible=["true" | "false"]
          android:enabled=["true" | "false"]
          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
          android:orderInCategory="integer" />
    <group android:id="@[+][package:]id/resource name"
           android:checkableBehavior=["none" | "all" | "single"]
           android:visible=["true" | "false"]
           android:enabled=["true" | "false"]
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="integer" >
        <item />
    </group>
    <item >
        <menu>
          <item />
        </menu>
    </item>
</menu>

 

العناصر:

عنصر <menu>

مطلوب. يجب أن يكون العقدة الأساسية. يحتوي على عنصر <item> و/أو عنصر <group>.

السمات:

xmlns:android

نطاق XML. مطلوبه. يحدد نطاق XML، والذي يجب أن يكون:
"http://schemas.android.com/apk/res/android".

عنصر <item>

عنصر قائمه. قد يحتوي على عنصر <menu> (لقائمة فرعية). يجب أن يكون تابع لعنصر <menu> أو لعنصر <group>.

السمات:

سمة android:id

معرف مصدر. معرف مصدر فريد. لإنشاء معرف مصدر جديد لهذا العنصر، أستخدم الشكل التالي: “@+id/name“. يشير رمز “+” إلى أنه يجب إنشاء هذا كمعرف جديد.

سمة android:title

مصدر سلسله. عنوان القائمة كمصدر سلسلة أو سلسلة خام.

سمة android:titleCondensed

مصدر سلسله. عنوان موجز كمصدر سلسلة أو سلسلة خام. يستخدم هذا العنوان لحالات يكون فيها العنوان العادي طويلاُ جداً.

سمة android:icon

مصدر رسوميات. صورة لتستخدم كأيقونة لعنصر القائمة.

سمة android:onClick

اسم داله. هي داله تستدعى عند النقر على عنصر القائمة هذا. يجب أن يتم الإعلان عن الداله في النشاط كـ عام، و قبول عنصر القائمة كعاملها الوحيد. الذي يشير إلى العنصر الذي تم النقر عليه. هذه الداله تأخذ الأولوية على الإستدعاء القياسي لـ ()onOptionsItemSelected. أنظر إلى المثال في الأسفل.

 

تحذير: إذا لم تقم بتوضيح كودك بإستخدام أداة ProGuard (أو أداة مشابهه)، تأكد من إستثناء الأسلوب الذي قمت بتعيينه في هذه السمة من خلال إعادة تسميته، لأنه يمكن أن يكسر الوظيفه.

سمات مقدمة في المستوى API 11

سمة android:showAsAction

كلمة أساسية. متى وكيف يجب أن يظهر هذا العنصر كعنصر فعال في شريط التطبيق. عنصر قائمة يمكن أن يظهر كعنصر فعال فقط عندما يحتوي النشاط على شريط تطبيق. القيم الصالحه:

القيمه الوصف
ifRoom إذا توفر مكان ضع هذا العنصر في شريط التطبيق فقط إذا توفر مكان له.

إذا لم يتوفر مكان لكافة العناصر التي تم وضع علامة “ifRoom” عليها، العناصر ذات القيم الأقل في “الترتيب في الصنف” orderInCategory يتم عرضها كإجراءات، ويتم عرض العناصر المتبقية في القائمة الكاملة “خارج الشاشه”.

withText مع نص قم أيضاً بتضمين نص العنوان (المحدد بواسطة android: title) مع عنصر الإجراء. يمكنك تضمين هذه القيمة مع إحدى القيم الأخرى كمجموعة أعلام “flag”، و أفصلها بالرمز |.
never أبداً لا تضع هذا العنصر أبداً في شريط التطبيق. بدلاً من ذلك، يمكنك إدراج العنصر في القائمة الكامله لشريط التطبيق.
always دائماً  ضع هذا العنصر دائماً في شريط التطبيق. تجنب إستخدام هذه القيمه إلا إذا كان من الضروري أن يظهر العنصر دائماً في شريط الإجراءات.

يؤدي تعيين عدة عناصر لتظهر دائماً كعناصر إجراء، إلى تداخلها مع واجهة مستخدم أخرى في شريط التطبيق.

 collapseActionView طي عرض الإجراء عرض الإجراء المرتبط مع عنصر الإجراء هذا قابل للطي (كما تم الإعلان عنه بواسطة  android:actionLayout أو android:actionViewClass) .

تم تقديمه في مستوى API 14.

 

لمزيد من المعلومات، راجع الفصل التدريبي “إضافة شريط التطبيقات” .

سمات مقدمة في المستوى API 11

سمة android:actionLayout

مصدر مخطط. مخطط يستخد كعرض فعال “نشط”.

لمزيد من المعلومات، راجع العروض النشطة و موفروا الأنشطه.

سمات مقدمة في المستوى API 11

سمة android:actionViewClass

اسم فئة. اسم فئة مؤهل بالكامل للمعاينه ليستخدم كمعاينه نشطه. مثال، “android.widget.SearchView” لإستخدام SearchView كمعاينة نشطه.

لمزيد من المعلومات، راجع العروض النشطة و موفروا الأنشطه.

تحذير: إذا لم تقم بتوضيح كودك بإستخدام أداة ProGuard (أو أداة مشابهه)، تأكد من إستثناء الأسلوب الذي قمت بتعيينه في هذه السمة من خلال إعادة تسميته، لأنه يمكن أن يكسر الوظيفه.

 

سمات مقدمة في المستوى API 11

سمة android:actionProviderClass

اسم فئة. اسم فئة مؤهل بالكامل لموفر الأنشطة ليستخدم في مكان العنصر النشط. مثال، “android.widget.ShareActionProvider” لإستخدام ShareActionProvider.

لمزيد من المعلومات، راجع العروض النشطة و موفروا الأنشطه.

تحذير: إذا لم تقم بتوضيح كودك بإستخدام أداة ProGuard (أو أداة مشابهه)، تأكد من إستثناء الأسلوب الذي قمت بتعيينه في هذه السمة من خلال إعادة تسميته، لأنه يمكن أن يكسر الوظيفه.

 

سمات مقدمة في المستوى API 14

سمة android:alphabeticShortcut

Char. هو حرف لمفتاح إختصار الأبجديه.

سمة android:numericShortcut

تستخدم المتغير عدد صحيح. هو رقم لمفتاح إختصار الأرقام.

سمة android:alphabeticModifiers

كلمة أساسية. معدّل للإختصار الأبجدي في عنصر القائمة. القيمة الإفتراضية تتوافق مع مفتاح التحكم. القيم الصالحة:

القيمه الوصف
META تتوافق مع مفتاح التعريف “meta”
CTRL تتوافق مع مفتاح التعريف “Control”
ALT تتوافق مع مفتاح التعريف “Alt”
SHIFT تتوافق مع مفتاح التعريف “Shift”
SYM  تتوافق مع مفتاح التعريف “Sym”
FUNCTION  تتوافق مع مفتاح التعريف “Function”

 

ملاحظة: يمكنك تحديد عدة كلمات رئيسية في إحدى السمات. على سبيل المثال، تشير android:alphabeticModifiers=”CTRL|SHIFT” إلى أنه للقيام بمطابقة عنصر القائمة، يحتاج المستخدم إلى ضغط كلٍ من مفاتيح CTRL + SHIFT + الاختصار.

 

يمكنك إستخدام الداله setAlphabeticShortcut() لتعيين قيم السمات برمجياً. لمزيد من المعلومات حول

سمة تعديل الأبجديه alphabeticModifier راجع alphabeticModifiers.

 

سمة android:numericModifiers

كلمة أساسية. معدّل للاختصار الرقمي في عنصر القائمة. القيمة الإفتراضية تتوافق مع مفتاح التحكم. القيم الصالحة:

 

القيمه الوصف
META تتوافق مع مفتاح التعريف “meta”
CTRL تتوافق مع مفتاح التعريف “Control”
ALT تتوافق مع مفتاح التعريف “Alt”
SHIFT تتوافق مع مفتاح التعريف “Shift”
SYM  تتوافق مع مفتاح التعريف “Sym”
FUNCTION  تتوافق مع مفتاح التعريف “Function”
ملاحظة: يمكنك تحديد عدة كلمات رئيسية في إحدى السمات. على سبيل المثال، تشير android:numericModifiers=”CTRL|SHIFT” إلى أنه للقيام بمطابقة عنصر القائمة، يحتاج المستخدم إلى ضغط كلٍ من مفاتيح CTRL + SHIFT + الاختصار.

 

يمكنك إستخدام الداله setNumericShortcut() لتعيين قيم السمات برمجياً. لمزيد من المعلومات حول سمة التعديل الرقمي numericModifier راجع numericModifiers.

سمة android:checkable

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا كان العنصر قابلاً للتحديد.

سمة android:checked

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا كان العنصر محدد إفتراضياً.

سمة android:visible

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا كان العنصر مرئي إفتراضياً.

سمة android:enabled

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا تم تمكين العنصر إفتراضياً.

سمة android:menuCategory

كلمة أساسيه. قيم متوافقه مع ثوابت كتالوج القائمة CATEGORY_* constants، التي تحدد أولوية العنصر. القيم الصالحة:

القيمه الوصف
container حاويه للعناصر التي هي جزء من “حاويه”.
system نظام للعناصر التي يتم توفيرها بواسطة “النظام”.
secondary ثانوي للعناصر التي هي خيارات “ثانوية” يوفرها المستخدم (نادراً ما تستخدم).
alternative بديل للعناصر التي تعتبر إجراءات “بديله” على البيانات التي يتم عرضها حالياً.

 

سمة android:orderInCategory

تستخدم المتغير عدد صحيح. ترتيب “أهمية” العنصر ، داخل المجموعه.

العنصر <group>

مجموعة قائمه (لإنشاء مجموعة من العناصر التي تتشارك نفس السمات، مثل هل هي: مرئية، ممكنه، قابلة

للتحديد). تحتوي على واحد أو أكثر من عناصر <item>. يجب أن يكون تابع لعنصر <menu>.

السمات:
سمة android:id

معرف مصدر. معرف مصدر فريد. لإنشاء معرف مصدر جديد لهذا العنصر، أستخدم الشكل التالي: “@+id/name“.

يشير رمز “+” إلى أنه يجب إنشاء هذا كمعرف جديد.

 

سمة android:checkableBehavior

كلمة أساسية. نوع سلوك إمكانية التحديد للمجموعة. القيم الصالحة:

 

القيمه الوصف
none لا يمكن إختياره
all يمكن إختيار جميع العناصر (بإستخدام مربع الإختيار)
single يمكن إختيار عنصر واحد فقط (بإستخدام الزر الدائري)

 

مصدر القائمة

 

سمة android:visible

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا كانت المجموعة مرئية.

سمة android:enabled

تمثل بالمتغير منطقي. تأخذ القيمة “true” إذا كانت المجموعة مُمكنه.

سمة android:menuCategory

كلمة أساسيه. قيم متوافقه مع ثوابت كتالوج القائمة CATEGORY_* constants، التي تحدد أولوية المجموعة. القيم الصالحة:

 

القيمه الوصف
container حاويه للمجموعات التي هي جزء من “حاويه”.
system نظام للمجموعات التي يتم توفيرها بواسطة “النظام”.
secondary ثانوي للمجموعات التي هي خيارات “ثانوية” يوفرها المستخدم (نادراً ما تستخدم).
alternative بديل للمجموعات التي تعتبر إجراءات “بديله” على البيانات التي يتم عرضها حالياً.

 

سمة android:orderInCategory

تستخدم المتغير عدد صحيح. الترتيب الإفتراضي للعناصر بداخل الكتالوج.

مثال:

ملف XML محفوظ في res/menu/example_menu.xml:

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item android:id="@+id/item1"
          android:title="@string/item1"
          android:icon="@drawable/group_item1_icon"
          app:showAsAction="ifRoom|withText"/>
    <group android:id="@+id/group">
        <item android:id="@+id/group_item1"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item1"
              android:icon="@drawable/group_item1_icon" />
        <item android:id="@+id/group_item2"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item2"
              android:icon="@drawable/group_item2_icon" />
    </group>
    <item android:id="@+id/submenu"
          android:title="@string/submenu_title"
          app:showAsAction="ifRoom|withText" >
        <menu>
            <item android:id="@+id/submenu_item1"
                  android:title="@string/submenu_item1" />
        </menu>
    </item>
</menu>

 

كود التطبيق التالي يقوم بتضخيم القائمة من خلال إستدعاء (onCreateOptionsMenu(Menu ويقوم أيضاً بالإعلان عن إستدعاء on-click لعنصرين:

KOTLIN 

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.example_menu, menu)
    return true
}

fun onGroupItemClick(item: MenuItem) {
    // One of the group items (using the onClick attribute) was clicked
    // The item parameter passed here indicates which item it is
    // All other menu item clicks are handled by <code><a href="/reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code>
}

JAVA

public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.example_menu, menu);
    return true;
}

public void onGroupItemClick(MenuItem item) {
    // One of the group items (using the onClick attribute) was clicked
    // The item parameter passed here indicates which item it is
    // All other menu item clicks are handled by <code><a href="/reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code>
}

 

 

 

 

 


للإطلاع على المقال باللغة الإنجليزية أضغط هنا.

الإعلانات