מושגים מרכזיים

בקטעים הבאים מוסברים כמה מושגים מרכזיים בתהליך הגרירה והשחרור.

תהליך הגרירה והשחרור

תהליך הגרירה והשחרור כולל ארבעה שלבים או מצבים: התחיל, שהמשיך, ירד והסתיים.

הפעולה התחילה

בתגובה לתנועת הגרירה של המשתמש, האפליקציה קוראת startDragAndDrop() כדי להורות למערכת להתחיל פעולת גרירה ושחרור. הארגומנטים של ה-method , והארגומנטים הבאים:

• הנתונים לגרירה.
• קריאה חוזרת (callback) לשרטוט של הצללית של הגרירה
• מטא-נתונים שמתארים את הנתונים שגוררים
• המערכת מגיבה בקריאה חוזרת לאפליקציה כדי לקבל גרירה צל. לאחר מכן המערכת מציגה את הצללית של הגרירה במכשיר.
• בשלב הבא, המערכת שולחת אירוע גרירה עם סוג הפעולה ACTION_DRAG_STARTED לאירוע הגרירה האזנה לכל האובייקטים של View בפריסה הנוכחית. שפת תרגום ימשיכו לקבל אירועי גרירה, כולל ירידה אפשרית אירוע – ה-listener לאירוע הגרירה חייב להחזיר true. זה רושם בין המאזינים למערכת. רק מאזינים רשומים ממשיכים אל לקבל אירועי גרירה. בשלב הזה, המאזינים יכולים גם לשנות את מראה של אובייקט שחרור היעד View כדי להראות שהתצוגה יכולה אישור של אירוע שחרור.
• אם ה-listener לגרירה מחזיר את הערך false, הוא לא מקבל גרירה אירועים של הפעולה הנוכחית עד שהמערכת תשלח אירוע גרירה עם סוג הפעולה ACTION_DRAG_ENDED. על ידי החזרת false, המאזינים יודיעו למערכת שהוא לא מעוניין במצב הגרירה והשחרור, והוא לא רוצה לקבל את הנתונים שגוררים.

התהליך ממשיך

המשתמשים ממשיכים בגרירה. כשצל הגרירה חוצה את תיבה תוחמת של יעד בענן, המערכת שולחת אירוע גרירה אחד או יותר אל האזנה לאירוע גרירה של היעד. ה-listener עשוי לשנות את המראה של ירידה ביעד View בתגובה לאירוע. לדוגמה, אם האירוע מציין שהצלל של הגרירה נכנס לתיבה התוחמת של השחרור יעד – סוג פעולה ACTION_DRAG_ENTERED – המאזינים יכולים להגיב באמצעות הדגשה של View.

בוטל

המשתמש משחרר את הצללית של הגרירה בתוך התיבה התוחמת של השחרור יעד. המערכת שולחת ל-listener של היעד ששחררת אירוע גרירה עם פעולה מקלידים ACTION_DROP. אובייקט אירוע הגרירה מכיל את הנתונים שמועברים למערכת קריאה ל-startDragAndDrop() שמתחילה את הפעולה. המאזינים הם צפוי להחזיר למערכת true בוליאני אם ה-listener בהצלחה מעבד את הנתונים שהושמטו. : שלב זה מתרחש רק אם המשתמש משחרר את הצללית של הגרירה בתוך תיבה תוחמת של View שהמאזין שלה רשום לקבלת אירועי גרירה (ירידה ביעד). אם המשתמש מסיר את הצללית של הגרירה אין אירוע גרירה ACTION_DROP שנשלח.

הסתיים

לאחר שהמשתמש משחרר את הצללית של הגרירה ואחרי המערכת שולחת

מחוץ לאירוע גרירה עם סוג הפעולה ACTION_DROP, במקרה הצורך, המערכת שולחת אירוע גרירה מסוג הפעולה ACTION_DRAG_ENDED כדי לציין פעולת הגרירה והשחרור הסתיימה. הפעולה הזו מתבצעת בלי קשר למיקום של המשתמש משחרר את הצללית של הגרירה. האירוע נשלח לכל מאזין רשום לקבלת אירועי גרירה, אפילו אם המאזינים גם מקבלים את אירוע מסוג ACTION_DROP.

כל אחד מהשלבים האלה מתואר בפירוט בקטע שנקרא פעולת גרירה ושחרור.

גרירת אירועים

המערכת שולחת אירוע גרירה בצורת אובייקט DragEvent, מכיל סוג פעולה שמתאר את מה שמתרחש בגרירה ובשחרור. תהליך האימות. האובייקט יכול להכיל גם נתונים אחרים, בהתאם לסוג הפעולה.

פונקציות event listener בגרירה מקבלים את האובייקט DragEvent. כדי לקבל את סוג הפעולה, שיחת מאזינים DragEvent.getAction() יש שישה ערכים אפשריים שמוגדרים על ידי קבועים במחלקה DragEvent, שמתוארים בטבלה 1:

טבלה 1. סוגי הפעולות של DragEvent

סוג הפעולה	משמעות
ACTION_DRAG_STARTED	האפליקציה קוראת ל-startDragAndDrop() ומקבלת צללית לגרירה. אם המאזינים רוצה להמשיך לקבל אירועי גרירה עבור פעולה זו, עליו להחזיר true בוליאני המערכת.
ACTION_DRAG_ENTERED	צל הגרירה נכנס לתיבה התוחמת של אירוע הגרירה View זהו סוג הפעולה הראשון של האירוע שה-listener מקבלת כשצל הגרירה נכנס לתיבה התוחמת.
ACTION_DRAG_LOCATION	בעקבות אירוע ACTION_DRAG_ENTERED, הצללית של הגרירה עדיין יציבה בתוך התיבה התוחמת של View.
ACTION_DRAG_EXITED	יש מעקב אחר ACTION_DRAG_ENTERED ולפחות פריט אחד האירוע ACTION_DRAG_LOCATION, הצללית של הגרירה זזה מחוץ לתיבה התוחמת של אירוע הגרירה View.
ACTION_DROP	צל הגרירה משתחרר מעל מקש ה-listener של אירוע הגרירה View סוג הפעולה הזה נשלח אל View ה-listener של האובייקט רק אם הוא מחזיר ערך בוליאני true בתגובה ל אירוע גרירה ACTION_DRAG_STARTED. סוג הפעולה הזה לא נשלחת אם המשתמש משחרר את הצללית של הגרירה מעל View שה-listener לא רשום, או אם המשתמש משחרר את הגרירה צל על כל דבר שלא חלק מהפריסה הנוכחית. ה-listener מחזיר true בוליאני אם הוא מתבצע עיבוד של הירידה. אחרת, הוא צריך להחזיר false
ACTION_DRAG_ENDED	המערכת מסיימת את פעולת הגרירה והשחרור. סוג הפעולה הזה לא בהכרח מופיע אירוע ACTION_DROP לפניו. אם המיקום המערכת שולחת ACTION_DROP, שמקבלת את סוג הפעולה ACTION_DRAG_ENDED לא מרמז הירידה הצליחה. המאזינים חייבים להתקשר getResult(), כפי שמוצג בטבלה 2, כדי לקבל את הערך הוחזרו בתגובה לACTION_DROP. אם אירוע אחד (ACTION_DROP) לא נשלח, ואז הפונקציה getResult() מחזירה false.

האובייקט DragEvent מכיל גם את הנתונים והמטא-נתונים שהאפליקציה מספק למערכת בקריאה ל-startDragAndDrop(). חלק מהנתונים תקף רק לסוגי פעולות מסוימים, כפי שמתואר בטבלה 2. לקבלת מידע נוסף מידע על אירועים והנתונים המשויכים אליהם, ראה את הקטע א פעולת גרירה ושחרור.

טבלה 2. נתוני DragEvent חוקיים לפי סוג הפעולה

ערך getAction()	ערך getClipDescription()	ערך getLocalState()	ערך getX()	ערך getY()	ערך getClipData()	ערך getResult()
ACTION_DRAG_STARTED	✓	✓
ACTION_DRAG_ENTERED	✓	✓
ACTION_DRAG_LOCATION	✓	✓	✓	✓
ACTION_DRAG_EXITED	✓	✓
ACTION_DROP	✓	✓	✓	✓	✓
ACTION_DRAG_ENDED		✓				✓

השיטות DragEvent getAction(), describeContents(), writeToParcel(), ו-toString() תמיד מחזיר נתונים חוקיים.

אם שיטה מסוימת לא מכילה נתונים תקינים לסוג פעולה מסוים, היא מחזירה null או 0, בהתאם לסוג התוצאה.

גרירת הצללית

במהלך פעולת גרירה ושחרור, המערכת מציגה תמונה שהמשתמש וגרירה. עבור תנועת נתונים, התמונה הזו מייצגת את הנתונים שגוררים. עבור פעולות אחרות, התמונה מייצגת היבט מסוים של פעולת הגרירה.

התמונה נקראת צללית של גרירה. אתם יוצרים אותו בשיטות שאתם מצהירים עליהן A View.DragShadowBuilder לאובייקט. מעבירים את ה-builder למערכת כשמפעילים את הגרירה והשחרור באמצעות startDragAndDrop(). כחלק מתגובה ל: startDragAndDrop(), המערכת מפעילה את שיטות הקריאה החוזרת (callback) שהגדרתם ב- View.DragShadowBuilder כדי לקבל צללית לגרירה.

למחלקה View.DragShadowBuilder יש שני מרכיבים:

View.DragShadowBuilder(View)

ה-constructor הזה מקבל את כל View אובייקטים. ה-constructor מאחסן את האובייקט View באובייקט View.DragShadowBuilder, אז הקריאות החוזרות יכול לגשת אליו כדי ליצור את הצללית של הגרירה. התצוגה לא חייבת להיות View שהמשתמש בוחר כדי להתחיל את פעולת הגרירה.

אם אתם משתמשים ב-constructor הזה, אין צורך להרחיב View.DragShadowBuilder או לשנות את השיטות שלו. כברירת מחדל, צריך לגרור צל בעל מראה זהה לזה של View שמעבירים כארגומנט, במרכז, מתחת למיקום שבו המשתמש נוגע במסך.

View.DragShadowBuilder()

אם משתמשים ב-constructor הזה, אף אובייקט View לא זמין אובייקט View.DragShadowBuilder. השדה מוגדר ל-null. עליך להאריך את התוקף View.DragShadowBuilder ולשנות את השיטות שלו, אחרת תקבלו צל גרירה בלתי נראה. המערכת לא גורמת לשגיאה.

במחלקה View.DragShadowBuilder יש שתי שיטות שיוצרות יחד את הגרירה צל:

onProvideShadowMetrics()

המערכת תפעיל את ה-method הזה מיד אחרי שתבצעו את הקריאה ל-startDragAndDrop(). משתמשים בשיטה כדי לשלוח את המימדים ואת נקודת המגע של צל הגרירה אל במערכת. השיטה כוללת שני פרמטרים:

outShadowSize: Point לאובייקט. רוחב הצללית של הגרירה נכנס x, והגובה שלו עוד יותר y

outShadowTouchPoint: אובייקט Point. נקודת המגע היא המיקום בצל הגרירה שחייב להיות מתחת לאצבע של המשתמש בזמן הגרירה. המיקום ה-X שלו ממוקם בx ומיקום ה-Y הוא y.

onDrawShadow()

מיד אחרי השיחה ל-onProvideShadowMetrics(), המערכת מתקשרת onDrawShadow() כדי ליצור את הצללית של הגרירה. ל-method יש ארגומנט, אובייקט Canvas המערכת יוצרת מהפרמטרים שאתם מספקים onProvideShadowMetrics() השיטה משרטטת את צל הגרירה Canvas

כדי לשפר את הביצועים, כדאי להקפיד שגודל הצללית לגרירה יהיה קטן. ליחיד מומלץ להשתמש בסמל. כדי לבחור פריטים מרובים, אפשר אם רוצים להשתמש בסמלים בערימה ולא בתמונות שלמות שמפוזרות על פני המסך.

גרירת פונקציות event listener ו-callback

View מקבל אירועי גרירה עם רכיב event listener לגרירה שמטמיע View.OnDragListener או באמצעות שיטת הקריאה החוזרת onDragEvent() של התצוגה. מתי שהמערכת קוראת ל-method או ל-listener, היא מספקת ארגומנט DragEvent.

ברוב המקרים, עדיף להשתמש ב-listener על פני שיטת הקריאה החוזרת. מתי בדרך כלל לא יוצרים מחלקות משנה של View, אבל משתמשים פעולת הקריאה החוזרת מאלצת אתכם ליצור מחלקות משנה כדי לעקוף את השיטה. לחשבון להשוואה, תוכלו להטמיע מחלקת מאזינים אחת ואז להשתמש בה עם אובייקטים שונים של View. אפשר גם להטמיע אותו ככיתה אנונימית מוטבעת או lambda. כדי להגדיר את ה-listener לאובייקט View, קוראים לפונקציה setOnDragListener().

לחלופין, אפשר לשנות את הטמעת ברירת המחדל של onDragEvent() בלי לשנות את השיטה. הגדרה OnReceiveContentListener בצפייה; פרטים נוספים זמינים במאמר setOnReceiveContentListener() השיטה onDragEvent() מבצעת את הפעולות הבאות כברירת מחדל:

• הפונקציה מחזירה את הערך True בתגובה לקריאה ל-startDragAndDrop().

• שיחות טלפון performReceiveContent() אם נתוני הגרירה והשחרור מושמטים בתצוגה. הנתונים מועברים בתור אובייקט ContentInfo. ה-method מפעילה את OnReceiveContentListener.

• הפונקציה מחזירה true אם נתוני הגרירה והשחרור מושמטים בתצוגה OnReceiveContentListener צורכת חלק כלשהו מהתוכן.

צריך להגדיר את OnReceiveContentListener כדי שיטפל בנתונים ספציפיים במיוחד לעסק שלך אפליקציה. לקבלת תאימות לאחור עד לרמת API 24, צריך להשתמש בגרסת Jetpack של OnReceiveContentListener

אפשר להשתמש ב-event listener לגרירה ושיטת קריאה חוזרת לאובייקט View, ב- במקרה הזה המערכת קוראת קודם ל-listener. המערכת לא קוראת ל- שיטת הקריאה החוזרת (callback) אלא אם ה-listener מחזיר false.

השילוב של השיטה onDragEvent() ו-View.OnDragListener הוא דומה לשילוב של onTouchEvent() ו-View.OnTouchListener בשימוש באירועי מגע.